


Techniques for Processing Relocatable Lists in PL/I 


This manual illustrates usage of PL/I list-processing facilities for processing 
relocatable data lists, pointer lists, and lists of lists. Relocatable lists are lists 
organized within an area of storage in a way that permits the area to be trans- 
mitted to and from an external storage medium without disturbing the linkage 
of list components in the area. Such organization also permits moving lists 
about in main storage. 


The information in this manual concerning data lists assumes knowledge of 
Introduction to the List Processing Facilities of PL/I (GF20-0015) and 
Techniques for Processing Data Lists in PL/I (GF20-0018). Some of the 
information in this manual assumes knowledge of Techniques for Processing 
Pointer Lists and Lists of Lists in PL/I (GF20-0019). The audience for this 
manual is assumed to be the experienced programmer. 


Illustrative programs were processed by the PL/I (F) Compiler (Version 5.1) 
under control of the IBM System/360 Operating System (Release 19). 
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Preface 


List processing in PL/I concerns programs which manipu- 
late the storage addresses and the contents of based vari- 
ables that are linked by contained locator variables. 
Techniques for using the list-processing facilities of PL/I to 
manipulate list components in main storage have been 
presented in Techniques for Processing Data Lists in PL/I 
(GF20-0018) and Techniques for Processing Pointer Lists 
and Lists of Lists in PL/I (GF20-0019). 

This manual discusses methods used to convert list com- 
ponents linked within an area by absolute storage addresses 
to list components linked within an area by relative storage 
addresses. These latter addresses are relative to the begin- 
ning of the containing area. Such lists are called relocatable 
lists because they can be transferred about in main storage 
or transmitted to and from external storage for subsequent 
processing. 

As indicated in the preceding manuals, the primary 
advantages of list-processing techniques are efficient main 
storage utilization and the ability to preserve the logical 
organization of complex data entities that do not lend 
themselves to convenient representation by conventional 
PL/I arrays and structures. Data of this type occurs in many 
nonnumeric applications, such as information storage and 

‘retrieval, system simulation, engineering design, computer- 
software production, text editing, and artificial intelligence. 
List processing preserves the natural structure of the data 
involved in such applications and reduces the complexity of 
related programs. The convenience of organizing data in list 
form is enhanced by the ability to transmit relocatable lists 
to and from external storage as needed by the application. 


This manual illustrates the techniques involving relocat- 
able lists with subroutine and function procedures that 
concentrate on specific aspects of creating and moving 
relocatable lists. Clarity of presentation has been empha- 
sized rather than efficient programming techniques. No 
attempt has been made to produce “production” code. 
Suitable inline code may be preferred for many applica- 
tions. 

Because processing lists in PL/I is an advanced program- 
ming topic, this manual assumes that the reader is an ex- 
perienced programmer with a knowledge of PL/I equivalent 
at least to that presented in A PL/I Primer (SC28-6808). 
Familiarity is assumed with array and structure organiza- 
tion and with methods for creating and invoking sub- 
routines and functions. In addition, knowledge of the 
information contained in the following publications is 
assumed: 


Introduction to the List Processing Facilities of PL/I 
(GF20-0015) 

Techniques for Processing Data Lists in PL/I 
(GF20-0018) 3 | 

Techniques for Processing Pointer Lists and Lists of Lists 
(GF20-0019) 


Information on the F-level list-processing facilities 
appears in JBM System/360: PL/I(F') Language Reference 
Manual (GC28-8201) and IBM System/360 Operating Sys- 
tem: PL/I(F) Programmer’s Guide (GC28-6594). 


Introduction 


The techniques developed for creating and processing lists 
in Techniques for Processing Data Lists in PL/I and Tech- 
niques for Processing Pointer Lists and Lists of Lists do not 
consider moving a list about in storage or a list to and from 
a file. The ability to store a list in a file is important be- 
_cause it allows a list to be processed in stages by successive 
runs of either the same program or any other designed to 
retrieve the list. . 

One approach to the external transmission of a list is to 
disassemble the components of the list and to write their 
associated data values successively into a file. Then, when 
the list is to be processed further, the data values can be 
retrieved from the file, and the list can be reconstructed 
component by component. Transmission of a list in this 
manner may have merit with simple linear data lists but 
becomes complicated and inefficient when applied to non- 
linear lists. A more desirable approach is to keep the list 
intact within its containing area and to write the area into 


the file as a unit; however, this method also presents a 
problem—pointer values within an area become invalid 
when the area is stored at a new location. Since there is no 
way of assuring that an area will occupy the same storage 
each time it is read from a file, the organization of a list 
contained in a retrieved area can generally be assumed to be 
destroyed because its linking pointers will be invalid at the 
new location. | 

PL/I overcomes this difficulty in the transmission of a 
list by providing special variables called offset variables, 
which are used in place of pointer variables and which 
remain valid when a list is moved to a new location. An 
offset variable is a storage address that is relative to the 
beginning of an area. This manual shows how offset vari- 
ables can be used to organize data lists, pointer lists, and 
lists of lists into relocatable form and how such lists can be 
written into and read from a file. 


Chapter 1. Organizing Relocatable Lists 


The organization of relocatable lists depends mainly upon 
two PL/I facilities: offset variables, and the assignment 
statement applied to area variables. A detailed presentation 
of these facilities appears in the companion manual. /ntro- 
duction to the List Processing Facilities of PL/I 
(GF20-0015). However, for the purposes of this chapter, 
the following discussions present a review of offset variables 
and area assignment and show how these facilities may be 
used to organize relocatable lists. The discussions also illus- 
trate how relocatable lists can be moved to new storage 
locations and how they can be transmitted to and from 
files. 


AREA ASSIGNMENT 
An area variable is declared with the following attribute: 
AREA [(size-expression)| 


The size expression determines the number of bytes of 
storage reserved for the area. However, the size expression 
is optional; when it is not used, an implementation-defined 
size is assumed by the PL/I compiler. An asterisk (*) may 
be used in place of the size expression when the area vari- 
able appears as a parameter in either a subroutine or a 
function. The asterisk causes the area parameter to assume 
the size of the associated area argument. 

An assignment statement can contain an area variable to 
the left of the equal sign provided the expression on the 
right is restricted to either another area variable or a func- 
tion reference that possesses an area value. Execution of an 
assignment statement that contains area variables effec- 
tively frees all allocations in the receiving area and then 
assigns the contents of the source area to the receiving area. 
Free-storage gaps are retained during the assignment, so 
that allocations within the assigned area maintain their 
locations relative to each other. 

Illustrations of area assignments appear in Figure 1.1. 
The shaded portions of the areas represent free storage that 
is available for further allocations of based variables within 
the areas. When the source area is smaller than the receiving 
area, the assigned area is, in effect, extended with free 
storage. Similarly, when the source area is larger than the 
receiving area, truncation of free storage occurs at the end 
of the assigned area. However, if the truncation involves 
allocated storage and not just free storage, the AREA ON- 
condition occurs, and the contents of the receiving area 
become undefined. If no ON-unit appears in an ON state- 


ment for the AREA condition, the operating system issues 
a comment and raises the ERROR condition. When an 
ON-unit is specified and normal return occurs from the 
ON-unit, program control returns to the point of inter- 
ruption. | 

When an area variable is allocated, it is automatically 
given the empty state, which indicates that no storage has 
been allocated for based variables within the area. An area 
that is not empty can be made empty by assigning to it the 
value of an empty area or the value of the built-in function 
EMPTY. The effect of such an assignment is to free all 
allocations of based variables within the receiving area. 
Note that the area itself does not become free but retains 
its storage in reserve for further allocations of based vari- 
ables. 

A reference to the built-in function EMPTY uses no 
arguments and consists solely of the keyword EMPTY. A 
reference to EMPTY cannot appear in an operational 
expression; the value of EMPTY is used only to free storage 
allocated in a specified area. 

Area assignment can be used to transmit any type of 
data from one area to another, but, as mentioned earlier, 
pointer values contained in the assigned area will generally 
be transmitted incorrectly. As a result, area assignment 
cannot be used to move a list linked by pointer variables; 
the addresses of the list components would not be known 
in the receiving area (see Figure 1.2). Note that assigning 
the head pointer in the source list to the intended head of 
the list in the receiving area would also be incorrect since 
the second head would specify the address of the first list 
component in the source area and not the address of the 
first list component in the receiving area. This difficulty in 
pointer transmission is overcome by replacing pointer vari- 
ables with relocatable variables called offset variables. 


OFFSET VARIABLES 


An offset variable is a storage address that is relative to the 
beginning of an area. An offset variable must be declared 
explicitly with the OFFSET attribute, which has the fol- 
lowing form: — oe 


OFFSET( area-variable) 
The area variable in parentheses must also be declared ex- 


plicitly and must be a based variable that is unsubscripted 
and has an implied or explicit level number of one. 
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Figure 1.1. How areas are assigned 
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B2 > BODY2 = B1 > BODY1; 
HE AD2 = HEAD1; 


Figure 1.2. Incorrect use of area assignment to move a list 


_ Examples: 


DECLARE 
AREAI AREA(2000) BASED(P1), 
O OFFSET(AREAI), 
- (M,N) OFFSET(AREA1) EXTERNAL STATIC, 
SWITCH CONTROLLED OFFSET(AREA1), 
T(5) OFFSET(AREA1) INTERNAL, 
1 A, 2 X CHARACTER(15), 2 Y OFFSET(AREA1); 


As shown in these examples, PL/I allows offset variables _ 
to be individual element variables or elements of arrays and 
structures. An offset variable can have any storage class and 
scope, and the usual default rules for these types of attri- 
butes also hold for an offset variable. 

The value of an offset variable is always treated as a 

relative address and never as an absolute address. The offset 
value is relative to the beginning of the area specified in the 
associated OFFSET attribute. Assume, for example, that 
Ol is an offset variable and that AREA] is an area variable 
declared as follows: 


DECLARE 
AREAI1 AREA BASED(A1), 
O1 (OFFSET(AREA1); 


Assume further that the value of O1 is 75. The O1 specifies 
the 75th storage position (in bytes) from the beginning of 
AREAI. 

Values are assigned to offset variables through the assign- 
ment statement. An offset variable can receive the value of 
another offset variable or the value of a pointer variable.) 
When the value of a pointer variable is assigned to an offset 
variable, the assigned pointer value is automatically ad- 
justed so that it becomes relative to the beginning of the 
area associated with the receiving offset variable. The | 
address arithmetic performed automatically by the PL/I 
program to obtain the offset value is equivalent in effect to 
the following calculation: 


Offset value = (Pointer value) - (Absolute address of area) 


Similar but reverse address arithmetic is performed auto- 
matically when an offset value is assigned to a pointer vari- 
able. The offset value is added to the absolute address of 
the area specified in the associated OFFSET attribute: 


Pointer value = (Offset value) + (Absolute address of area) 


Note that these calculations are performed automatically 
by the PL/I program; the programmer cannot apply explicit 
arithmetic operations to offset variables in the source pro- 
gram. | 

When the value of an offset variable is assigned to. 
another offset variable, no address arithmetic is performed; 


the assignment is direct, so that both offset variables have 
the same value. : 

The following example shows how values are assigned to 
offset variables and how the absolute address of a data item 
is obtained in an assigned area: 


DECLARE 
AREA1 AREA(500) BASED(A1), 
AREA2 AREA(500) BASED(A2), 
O1 OFFSET(AREA1), 
O2 OFFSET(AREA2), 
DATA_ITEM BASED (P1) CHARACTER(80); 


ALLOCATE AREAI1 SET(A1); 
ALLOCATE AREA2 SET(A2); 
ALLOCATE DATA_ITEM IN(A1—>AREA1) SET(P1); 


A2—>AREA2 = Al—>AREAI; 


O1=P1; 
02 =0O1; 
P2 = 02; 


AREA] and AREA2 are area variables, each of which 
reserves 500 bytes of based storage; O1 is an offset variable 


— associated with AREAI, and O2 is an offset variable as- 


sociated with AREA2. The based variable DATA_ITEM is 
a character string that requires 80 storage bytes. 

When storage is allocated for AREA1, the absolute 
address of the allocation is assigned to pointer Al. Simi- 
larly, pointer A2 receives the absolute address of the stor- 
age allocated for AREA2. For example, Figure 1.3 assumes 
that AREAI is allocated at location 2000 and that AREA2 
is allocated at location 4025. The allocation of DATA _ 
ITEM in Al—>AREA1 is also assumed to occur at location 
2075, which is assigned to pointer P1. 

After Al—>AREA1I is assigned to A2—>AREAZ2, both 
areas contain equivalent storage configurations, as shown in 
Figure 1.3. Assignment of pointer P1 to offset O1 produces 
the relative address (75 = 2075 - 2000) of DATA_ITEM 
within Al—>AREAI. This relative address remains un- 
changed when assigned to offset O2. Assignment of O2, in 
turn, to P2 produces the absolute address (4100 = 75 + 
4025) of DATA_ITEM in A2—>AREAZ2. Reference to 
DATA _ITEM in A2—>AREA2 is then possible with the 
expression P2—>DATA_ ITEM. (Note that an offset vari- 
able cannot be used to qualify a based variable.) The 
broken lines in Figure 1.3 distinguish offset variables from 
pointer variables. 
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A2 > AREA2 = A1>AREAT1; 
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/* ASSIGN A1 > AREA1 TO A2 > AREAZ. */ 


O1 = Pl; /* SET O01 TO RELATIVE ADDRESS OF DATA_ITEM IN At 7 AREA1. i a 


O2=01; 
P2 = O2;: 


/* SET O2 EQUAL TO O01. */ 
/* SET P2 TO ABSOLUTE ADDRESS OF DATA_ITEM IN A2 > AREA2. */ 


Figure 1.3. Obtaining the absolute address of a data item in an assigned area 


Offset values and pointer values form a special type of 
program control data called the locator type. Locator data 
cannot be converted to any other type, nor can any other 
type of data be converted to locator type. Offset variables 
can receive offset and pointer values only; the same restric- 
tion applies to pointer variables. 

A null offset value may be assigned to an offset variable 
through the built-in function NULLO, which uses no argu- 
ments and consists solely of the keyword NULLO. A refer- 
ence to this function produces a null offset address, which 
does not specify any relative storage location. 

Although pointer values may be assigned to offset vari- 
ables and offset values may be assigned, in turn, to pointer 
variables, a null offset value cannot be assigned to a pointer 
variable, nor can a null pointer value be assigned to an off- 
set variable. These restrictions apply not only to explicit 
references to NULL and NULLO but also to assigned vari- 
ables that currently have null pointer or null offset values. 

Assume, for example, that P is a pointer variable and O 
is an offset variable. Then P can be assigned to O provided 
that P does not have a null value. When the value of P may 
be null, an IF statement can be used to ensure proper 
assignment: 


IF P= NULL 
THEN O = NULLO; 
ELSE O=P; 


A similar statement governs the correct assignment of O to 
P: | 


IF O= NULLO 
THEN P = NULL; 
ELSE P= 0; 


As with pointer variables, the comparison operators equal 
(=) and not equal (F) are the only operators that can use 
offset variables as operands. 


Offset variables, as well as pointer variables, can serve as’ 
arguments and parameters. An offset argument associated 
with an offset parameter or a pointer argument associated 
with a pointer parameter requires no conversion and there- 


fore produces no dummy argument. But an offset argument 


associated with a pointer parameter or a pointer argument 
associated with an offset parameter does require conversion 
and will produce a dummy argument. Also, when an offset 
argument is associated with an offset parameter, both must 
be offset with respect to the same area for the argument- 
parameter association to be meaningful. 

Although the area variable specified in the OFFSET 
attribute for an offset variable must be a based area, it is 
possible to associate an offset variable with an area that is 
not based. Consider the following statements: 


DECLARE 
AREA1 AREA(2000), 
DUMMY_AREA AREA(2000) BASED 
(DUMMY POINTER), | 
O OFFSET(DUMMY AREA); 


DUMMY _POINTER = ADDR(AREAI1); 


AREA1 and DUMMY _ AREA are area variables. AREA1 


reserves automatic storage, and DUMMY_AREA reserves 


based storage. The OFFSET attribute for variable O uses 
DUMMY _AREA and thus satisfies the requirement that 
the area specified in an OFFSET attribute must be based. 


When the address of AREA] is assigned to DUMMY _ 
POINTER, DUMMY __AREA becomes equivalent to 
AREA\I. Subsequent references to offset variable O are 
then effectively associated with AREAI. 

The size declared for DUMMY _AREA in the previous 
example does not have to be the same as the size of AREA1 
and can even be zero. The only purpose of DUMMY _ 
AREA is to provide a level-one based area variable for the 
OFFSET attribute of variable O, so that variable O can be 
made relative to the starting address of AREA1. The size of 
DUMMY _ AREA is not important, because it does not 
affect the starting address assigned to DUMMY_AREA 
through DUMMY _ POINTER. 


RELOCATABLE ORGANIZATIONS FOR 
DATA LISTS, POINTER LISTS, AND 
LISTS OF LISTS 


A relocatable list has the same organization as an absolute 
list except that offset variables rather than pointer variables 
are used to link the components of the relocatable list. This 
section presents illustrations of relocatable organizations 
for data lists, pointer lists, and lists of lists and shows how 
such lists may be moved from one location to another with- 
in internal storage. However, procedures for actually con- 
structing relocatable lists are deferred to Chapter 2. The 
~ emphasis in this section is upon the use of offset variables 
as component links in relocatable lists. | 
Figure 1.4 illustrates the organization of a relocatable 
data list and shows the PL/I statements that can be used to 
move the list to a new location. Broken lines, instead of 


B1—~BODY1 


eae 


B2 > BODY2 


OHEAD2} | 


solid lines, indicate the offset links (OL’s) and offset head 
of each list in the figure. Actual values (in decimal) are 
assumed for the offset variables to show that they remain 
unchanged when the list is moved. 

Two assignment statements perform the relocation of 
the data list in Figure 1.4: 


B2—>BODY2 = B1—>BODY1; 
OHEAD2 = OHEADI; 


The based area B1—>BODY 1 contains the body of the list, 
which is assigned to the based area B2—>BODY 2. The 
offset variable OHEAD2 receives the offset head OHEAD1 
of the list. The effect of these assignments is to produce a 
separate copy of the original data list. 

Since an offset variable cannot be used to qualify a 
based variable, it is not possible to refer to a component of 
a relocatable list unless the absolute address of the com- 
ponent is used. As an example, the following statements 
show how to obtain the absolute address of the last com- 
ponent in each of the relocatable data lists illustrated in 
Figure 1.4: 


DECLARE 
BODY1 AREA(500) BASED(B1), 
BODY2 AREA(500) BASED(B2), 

1 COMPONENT! BASED(P1), 
2 DATA CHARACTER(1), ! 
20L OFFSET(BODY1), 
1 COMPONENT2 BASED(P2), 
2 DATA CHARACTER(1), 
20L OFFSET(BODY2), 








B2 >BODY2=B1—>BODY1;: 
OHEAD2 = OHEAD!1; 


Figure 1.4. Assigning a relocatable data list to a new area 


OHEAD1 OFFSET(BODY1), Oo | offset head OHEAD2 are declared to be offset with respect 
OHEAD2 OFFSET(BODY2); ac 7 to BODY2. After the above statements are executed, 
tens a pointer Pl contains the absolute address of the last com- 
ponent in B1—>BODY1, and pointer P2 contains the abso- 
lute address of the last component.in B2—>BODY?2. The 


Pl = OHEAD!; . data elements of these two components can then be refer- 
P1 = P1—>COMPONENT1.OL; | red to with the following expressions: 

Pl = P1—>COMPONENT1.0L; | ? 
P2 = OHEAD?; | | P1—>COMPONENT!1 .DATA 


P2 = P2—>COMPONENT2.0L; | P2—>COMPONENT2.DATA 
P2 = P2—>COMPONENT2.0L; / 
Figure 1.5 illustrates the organization of a relocatable 

pointer list and shows how the list can be moved to a new 
area. Three assignment statements are used to move the list: 


These statements specify that the area variables BODY 1 OHEAD2 = OHEADI; 

and BODY? each reserve 500 bytes of based storage and B2—>BODY2 = B1—>BODY1; 

that the based variable DATA associated with each list D2—>DATA_AREA2 = DI—>DATA_AREAI; 
component is a character string that contains one character. 

The offset links (OL’S) in B1—>BODY 1 and the offset Note that each component of the list contains two offset 
head OHEAD1 are declared to be offset with respect to variables: the offset link OL and the offset data pointer 


BODY 1. Similarly, the offset links in B2—>BODY?2 and the ODP. Both elements must use offset values because pointer 
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OHEAD2 = OHEAD1; 
B2—>BODY2 = 81 —>BODY1; 
D2 >DATA_AREA2 = D1 >DATA_AREA1; 


Figure 1.5. Assigning a relocatable pointer list to a new area 


values become invalid when moved by area assignment. 
Movement of the data area of a relocatable pointer list is 
optional; if the data area is not moved, it can be shared 
between the old and new versions of the list body. 

As with relocatable data lists, offset variables cannot 
appear as qualifying pointers in references to the based 
components of a relocatable pointer list; absolute addresses 
must serve as the qualifying pointers. The following state- 
ments show how to obtain the absolute address of the last 
data item in each of the relocatable pointer lists illustrated 
in Figure 1.5: 


DECLARE 

BODY1 AREA(500) BASED(B1), 
BODY2 AREA(500) BASED(B1), 
DATA_AREA1 AREA(500) BASED(D1), 
DATA _ AREA2 AREA(500) BASED(D2), 
1 COMPONENT1 BASED(P1), 

2 ODP OFFSET(DATA_AREAI), 

2 OL OFFSET(BODY1), 
1 COMPONENT?2 BASED(P2), 

2 ODP OFFSET(DATA_AREA2), 

2 OL OFFSET(BODY?2), 
OHEAD1 OFFSET(BODY1), 
OHEAD2 OFFSET(BODY?2), 
DATA_ITEM BASED(DATA1) CHARACTER(1), 
(DATA1,DATA2) POINTER; | 


Pi = OHEAD!1; 

Pi = P1—>COMPONENT1.0L; 

Pi = P1 ->COMPONENT1.0L; 
DATA1 = P1—>COMPONENT1.ODP; 
P2 = OHEAD?; 

P2 = P2—>COMPONENT2.0L; 

P2 = P2—>COMPONENT2.0L; 
DATA2 = P2—>COMPONENT2.0DP; 


These statements specify that the area variables BODY 1, 
BODY2, DATA _AREA1, and DATA_AREA2 each reserve 
500 bytes of based storage and that the based variable 

- DATA_ITEM associated with each list component is a 
character string that contains one character. The offset 
links (OL’s) in B1—>BODY 1 and the offset head OHEAD1 
are declared to be offset with respect to BODY1. Since the 
data items associated with the list are located in 
D1—>DATA_AREAI, the offset data pointers (ODP’s) in 
B1—>BODY 1 are offset with respect to DATA_ AREAI1. 
Similarly, the offset links (OL’s) in B2—>BODY2 and the 
offset head OHEAD?2 are declared to be offset with respect 


‘to BODY2, and the offset data pointers (ODP’s) in 


B2—>BODY?2 are offset with respect to DATA AREA2. 

After the above statements are executed, pointer 
DATAI contains the absolute address of the data item 
associated with the last component in B1—>BODY 1, and 
pointer DATA2 contains the absolute address of the data 
item associated with the last component in B2—>BODY?2. 
The following expressions can then be used to refer to these 
two data items: 


DATA1—>DATA_ITEM 
DATA2—>DATA_ITEM 


Figure 1.6 illustrates the organization of a relocatable 
list of lists and shows how the list can be moved to a new 
area. As with relocatable pointer lists, three assignment 
statements are used to move the relocatable list of lists: 


OHEAD? = OHEADI1: 
B2—>BODY?2 = B1—>BODY1: 
D2—>DATA_AREA2=DI-—>DATA_AREAI; 


Again, each component of the list contains two offset vari- 
ables: the offset link OL and the offset value pointer OVP. 
A third element, however, appears in each component of a 
relocatable list of lists, namely, the type code T, which 
determines whether the offset value pointer (OVP) specifies 
the offset address of another list component (type code L) 
or the offset address of a data item (type code D). 

The following statements show declaration of type code 
T and how to obtain the absolute address of the last data 
item in each of the relocatable lists of lists illustrated in 
Figure 1.6: 


DECLARE 
BODY1 AREA(500) BASED(B1), 
BODY2 AREA(500) BASED(B2), 

DATA _AREAI AREA(500) BASED(D1), 
DATA_AREA2 AREA(500) BASED(D2), 
1 D COMPONENT! BASED(P1), 


2 CHARACTER(1), 

2 PAD  CHARACTER(3), 

2 OVP  OFFSET(DATA_AREA\I), 

2 OL  OFFSET(BODY1), | 
/*THE PAD ELEMENTS ALIGN THE OFFSETS ON 
FOUR-BYTE BOUNDARIES*/ 

1 L_COMPONENT1 BASED(P1), 

2 CHARACTER(1), 

2 PAD  CHARACTER(3), 

2 OVP  OFFSET(BODY1), 

2 OL  OFFSET(BODY1), 

1 D_COMPONENT2 BASED(P2), 
> Ar CHARACTER(1), 

2 PAD  CHARACTER(3), 


B1—BODY1 






OHEAD2 = OQHEAD1; 








L DATA_ITEM 


OVP 


DATA_ITEM 


B2 ~>BODY2 = B1 > BODY1; 
D2 >~DATA_AREA2 = D1 > DATA_AREAT1; 


Figure 1.6. Assigning a relocatable list of lists to a new area 


2 OVP  OFFSET(DATA_AREA2), 
2 OL OFFSET(BODY?2), 
1 L_COMPONENT2 BASED(P2), 
2 CHARACTER(1), 
2 PAD CHARACTER(3), 
2 OVP  OFFSET(BODY2), 
2 OL OFFSET(BODY2), 
OHEAD1 OFFSET(BODY1), 
OHEAD2 OFFSET(BODY2), 
DATA_ITEM BASED(DATA1) CHARACTER(1), 
(DATA1, DATA2) POINTER; a 


Pl = OHEADI: 
P1 =P1—>L_COMPONENT1.OVP: 
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P1 = P1—>D_COMPONENT1.OL; 
DATA1 = P1—>D_COMPONENT].OVP; 
-P2=OHEAD2; — 
P2 = P2—>L_COMPONENT2.0VP; 
P2 = P2->D_COMPONENT2.0L; 
DATA2 = P2—>D_COMPONENT2.0VP; 


These statements specify that the area variables BODY 1, 
BODY2, DATA_AREA1, and DATA_AREA2 each reserve 
500 bytes of based storage and that the based variable 
DATA_ITEM associated with each list component is a 
character string that contains one character. Because area 


_B1—>BODY 1 contains two types of components 


(D-components and L-components), separate declarations 
(D_COMPONENT1 and L_COMPONENT1) are given for 
each type. The distinction between the two types of com- 
ponents is that the offset value pointer (OVP) in D__ 
COMPONENT1 is offset with respect to DATA _AREAI, 
while OVP in L_COMPONENT]1 is offset with respect to 
BODY 1. However, the offset link (OL) in each type of 


component is offset with respect to BODY1, and both use a 


single character for the type code (T). Similarly, the two 
types of components in B2—>BODY?2 are declared as D__ 
COMPONENT2 and L_COMPONENT?2. The offset value 
pointer (OVP) in D_- COMPONENT? is offset with respect 
to DATA_AREA2, and OVP in L_COMPONENT?2 is off- 
set with respect to BODY2. Also, the offset link (OL) for 
each component type in B2—>BODY?2 is offset with 
respect to BODY2, and both types of components use a 
single character for the type code (T). 


INPUT AND OUTPUT STATEMENTS 
FOR RELOCATABLE LISTS 


The preceding discussions describe how to move a relocat- 
able list from one location to another within internal stor- 
age. The main reason, however, for organizing a list in 
relocatable form is to allow it to be recorded on an external 
storage medium, such as magnetic tape or magnetic disk, 
from which it can be retrieved for further processing at a 
later time. Transmission of a relocatable list to and from an 
external file requires input and output statements for read- 
ing and writing the list. Since PL/I does not permit stream- 
oriented input and output statements (such as GET and 
PUT) to read and write the values of pointer variables and 
offset variables, record-oriented statements (such as READ 
and LOCATE) must be used to transmit a relocatable list to 
and from a file. The following discussions describe the 
effect of the LOCATE and READ statements upon relocat- 
able lists. 


The LOCATE Statement 


Output transmission of a relocatable list is performed with 
the LOCATE statement, which has the following form: 


LOCATE based-variable 
FILE (file-name) 
[SET (pointer-variable)] ; 


This statement processes sequentially accessed files that are 
buffered, and allocates within an output buffer (auto- 
matically provided for the file) the next available storage 
position for the specified based variable. The location of 
the allocated storage is assigned to the pointer variable 
given in the SET option. The pointer variable allows proper 
qualification of references to the based variable in the 


buffer. A SET option, however, need not appear in the 
LOCATE statement; when it does not, an implied SET is 
assumed, which uses the pointer variable in the BASED 
attribute of the specified based variable. After the LOCATE 
statement has been executed, values can be assigned to the 
based variable in the buffer. If the based variable is a struc- 
ture, it may require padding elements for boundary align- 
ment. 

Successive executions of the LOCATE statement 
produce successive allocations of storage in the buffer. An 
attempt to execute a LOCATE statement when the buffer » 
has become full, momentarily suspends execution of the 


~ LOCATE statement and automatically causes the contents 


of the buffer to be transmitted as a block to the associated 
file. The buffer is then cleared, and storage is allocated at 
the beginning of the buffer for the suspended LOCATE 
statement. 
The following statements show how the LOCATE state- 
ment may be used to write a relocatable data list into a file: 


DECLARE 
OHEAD OFFSET(BODY), 
BODY AREA(500) BASED(B), 
1 LIST RECORD BASED(RECORD_ POINTER), 
2 R_HEAD OFFSET(DUMMY_BODY), 
2 PADDING CHARACTER(4), 
/*PADDING ALIGNS R_ BODY ON AN EIGHT-BYTE 
BOUNDARY IN THE OUTPUT BUFFER*/ 
2 R BODY AREA(S500), 
DUMMY BODY AREA BASED(DUMMY_ POINTER), 
OUTFILE FILE RECORD OUTPUT: 


LOCATE LIST RECORD 
FILE(OUTFILE) SET(RECORD_ POINTER), 
DUMMY _POINTER = ADDR 
(RECORD_POINTER-—>R_ BODY); 
RECORD _ POINTER—>R_HEAD = OHEAD; 
RECORD_POINTER—>R_BODY = B—>BODY; 


Figure 1.7 illustrates the effect of these statements. 
B—>BODY and OHEAD form the body area and offset 
head of the relocatable data list that is transmitted to the 
output file OUTFILE. Each record in the file is formed 
from the based variable LIST_RECORD, which contains 
two elements: R_- HEAD and R_BODY. R_HEAD receives 
the value of OHEAD, and R_ BODY receives the contents 
of B—>BODY. 

Observe that R_ HEAD is declared to be offset with 
respect to the based area DUMMY _BODY. Actually, 
R_HEAD should be offset with respect to based area © 
R_BODY because R_HEAD contains the relative address 
of the first list component in R_ BODY. But R_ BODY has 
a level number of two and, therefore, does not satisfy the 
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Figure 1.7. How a relocatable data list is transmitted as a logical record to a file 


requirement that the based area in an OFFSET attribute 
must have a level number of one. However, R_HEAD 
becomes effectively offset with respect to R_ BODY when 
DUMMY _ BODY and R_ BODY are made to occupy the 
same location. This overlay is achieved by assigning the 
address of R_ BODY to the pointer variable DUMMY _ 
POINTER associated with DUMMY_AREA. | 

_ This example assumes that environmental information, 
such as record type, record size, block size, input/output 
device type, unit number, and recording density, is speci- 
fied in a data definition (DD) statement within the job step 
that calls for execution of the program under the operating 
system. The block size determines the size of the buffer, 
which in Figure 1.7 is assumed to contain storage for four 
allocations of LIST RECORD. Also note that, when the 
size of LIST_RECORD is given in the appropriate DD — 
statement, the size must include additional storage for the 
internal control information associated with R_ BODY. For 
example, the F-level version of the PL/I compiler adds 16 
bytes of internal control information to each area variable. 
Additional information on this point appears in JBM Sys- 
tem/360 Operating System: PL/I(F) Programmer’s Guide 
(GC28-6594). | | 

When the contents of the output buffer are transmitted 


to the file, they are written as a block (also called a physical 
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record). Figure 1.7 shows successive blocks recorded in 
OUTFILE, which is assumed to be on magnetic tape. Each 
block is separated by an interblock gap (IBG) and contains 


up to four logical records (that is, four allocations of LIST 


_RECORD). The number of logical records in a block can 
be changed by specifying a different block size in the 
associated DD statement. | 

The transmission of a relocatable data list to an external 
file has been discussed. The following discussion pertains 
to the transmission of relocatable pointer lists and lists of 
lists to an external file. | 

To write a relocatable pointer list or list of lists into a 
file, it is necessary to transmit the data area of the list along 
with its head and body. The following statements show 
how the head, body, and data area can be combined into a 
single logical record: 


DECLARE 

OHEAD OFFSET(BODY), 

BODY AREA(500) BASED(B), 

DATA_AREA AREA(500) BASED(D), 

1 LIST_RECORD BASED(RECORD POINTER), | 
2 R_HEAD OFFSET(DUMMY BODY), 
2 PADI CHARACTER(4), 
2 R_BODY AREA(S500), 


2 PAD2 CHARACTER(4), 

2 R_DATA AREA AREA(S500), 
DUMMY _ BODY AREA BASED(DUMMY_ POINTER), 
OUTFILE FILE RECORD OUTPUT; 


LOCATE LIST RECORD 
FILE(OUTFILE) SET(RECORD_ POINTER): 
DUMMY _ POINTER = ADDR(RECORD_POINTER—> 
R_ BODY); 
RECORD POINTER->R HEAD = OHEAD; 
RECORD _ POINTER—>R_BODY = B—>BODY; 
RECORD POINTER—>R DATA AREA =D-—> 
DATA AREA: 


These statements apply to both pointer lists and lists of lists 
because each type of list contains a head, a body, and a 
data area. The statements are also similar to those of the 
preceding example except that the data area of the list is 
included in the record transmitted to the file. 

Inclusion of the data area in the logical record, however, 
may cause the record size to become too large and thus 


require additional buffer storage. A more convenient record 


size can be obtained by splitting the list into two logical 
records. The first record can contain the head and body of 
the list, and the second record can contain the data area. 
This type of transmission is obtained with the following 
statements: 


DECLARE 
OHEAD OFFSET(BODY), 
BODY AREA(500) BASED(B), 
DATA_AREA AREA(500) BASED(D), 
1 HEAD BODY RECORD BASED(RECORD _ 
POINTER), 
2 R_HEAD OFFSET(DUMMY_ BODY), 
2 PAD CHARACTER(4), 
2 R_BODY AREA(S500), 
DUMMY BODY AREA BASED(DUMMY _POINTER), 
OUTFILE FILE RECORD OUTPUT; 


LOCATE HEAD BODY RECORD 
FILE(OUTFILE) SET(RECORD_POINTER); 
DUMMY POINTER = ADDR(RECORD_POINTER-—> 
R_BODY); 
RECORD _POINTER—>R_HEAD = OHEAD; 


RECORD POINTER—>R_ BODY = B—>BODY; 
LOCATE DATA_AREA 
FILE(OUTFILE) SET(RECORD_ POINTER); 
RECORD POINTER—>DATA_AREA = D—> 
DATA_ AREA; 


Figure 1.8 illustrates the effect of these statements on a 
relocatable list of lists. The first LOCATE statement 
obtains storage in the output buffer for the logical record 
HEAD BODY RECORD, which receives the head and 
body of the relocatable list. The second LOCATE state- 
ment allocates storage in the output buffer for DATA _ 
AREA, which is written as an individual logical record. The 
buffer in Figure 1.8 contains four logical records (for two 
lists), with HEAD_BODY_RECORD and DATA_AREA 
occupying alternate positions. When the buffer becomes 
full it is automatically written into OUTFILE and cleared 
for further transmission. 


The READ Statement 


After relocatable lists have been written into a file, they can 
be retrieved from the file for additonal processing. Retrieval 
is accomplished with a READ statement: 


READ FILE(file-name) SET(pointer-variable); 


This statement obtains the location of the next logical 
record in an input buffer associated with the specified file 
and assigns the location to the pointer variable given in the 
SET option. A based variable qualified by the same pointer 
will then relate to the fields of the logical record; the based 
variable is effectively overlaid on the logical record in the 
buffer. 

The following statements demonstrate how a relocatable 
data list can be read from a file: 


DECLARE 
OHEAD OFFSET(BODY), 
BODY AREA(500) BASED(B), 
1 LIST RECORD BASED(RECORD POINTER), 
2 R_HEAD OFFSET(DUMMY_ BODY), 
2 PAD CHARACTER(4), 
2 R_BODY AREA(S00), 
DUMMY BODY AREA BASED(DUMMY POINTER), 
INFILE FILE RECORD INPUT; 
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Figure 1.8. How a relocatable list of lists is transmitted as two logical records to a file 


READ FILE(INFILE) SET(RECORD_ POINTER); 

DUMMY POINTER=ADDR 
(RECORD_POINTER—>R_BODY); 

OHEAD = RECORD _POINTER—>R_HEAD: 

B—>BODY = RECORD POINTER—>R_ BODY); 


Figure 1.9 illustrates the effect of these statements. The 
READ statement obtains the address of the next occur- 
rence of LIST_RECORD in the input buffer associated 
with INFILE and assigns the address to RECORD _ 
POINTER. The head and body of the relocatable list are 


then assigned to OHEAD and B—>BODY by the following 


statements: 
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OHEAD = RECORD_POINTER—>R_HEAD: 
B—>BODY = RECORD_POINTER—>R_BODY; 


Each execution of the READ statement advances the 
value of RECORD POINTER to the location of the next 


_ logical record in the buffer. When the end of the buffer is 


reached and an attempt is made to read another logical 
record, the program automatically refills the buffer with 
the next block from INFILE and assigns the address of the 
first logical record in the buffer to RECORD_ POINTER. 
This process is repeated until the end of the file is reached. 

_ When a relocatable pointer list or list of lists is read from 
a file, the data area of the list must also be retrieved along 


with the head and body of the list. The following state-. 


ments show how to read a relocatable pointer list or list of 
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l‘igure 1.9. How arelocatable data list is retrieved as a logical record from a file 





lists when the head, body, and data area are contained in a | D—>DATA_AREA = RECORD_POINTER—> 
single logical record: R_DATA_ AREA; 
DECLARE 


OHEAD OFFSET(BODY), 
BODY AREA(500) BASED(B), 


DATA AREA AREA(500) BASED(D), | These statements retrieve either a relocatable pointer list or 
1 LIST RECORD BASED(RECORD_ POINTER), a relocatable list of lists because both types contain a head, 

2 R_HEAD OFFSET(DUMMY_ BODY), i a body, and a data area. This example is similar to the 

2 PADI CHARACTER(4), | preceding example except that, in this example, the re- 

2 R_BODY AREA(500), : trieved record contains a data area. 

2 PAD2 CHARACTER(4), | Had the list originally been split and recorded in the file 

2 R_DATA_AREA AREA(S500), as two logical records, one for the head and body, the other 
DUMMY BODY AREA BASED(DUMMY_ POINTER), for the data area, then the following statements could be 
INFILE FILE RECORD INPUT; | used to retrieve the list: 

DECLARE 
OHEAD OFFSET(BODY), 

READ FILE(INFILE) SET(RECORD _ eee BODY AREA(500) BASED(B), 
DUMMY _ POINTER = ADDR DATA AREA AREA(500) BASED(D), 

(RECORD_POINTER—>R_BODY),; 1 HEAD BODY RECORD BASED(RECORD _ 
OHEAD = RECORD POINTER—>R_HEAD; POINTER), | 
B—>BODY = RECORD _POINTER—> _ 2 R_HEAD OFFSET(DUMMY_ BODY), 

R_ BODY; : 2 .PAD CHARACTER(4), 
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2 R_BODY AREA(500), 
DUMMY _BODY AREA BASED(DUMMY POINTER), 
INFILE FILE RECORD INPUT; 


READ FILE(INFILE) SET(RECORD_POINTER); 
DUMMY POINTER = ADDR(RECORD_ POINTER—> 
R_BODY); 
OHEAD = RECORD POINTER—>R_ HEAD; 
B—>BODY = RECORD POINTER—> 
R_BODY; 
READ FILE(INFILE) SET(RECORD _ POINTER); 
D—>DATA_AREA = RECORD _POINTER—> 
DATA_ AREA; 


INFILE 
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Figure 1.10 illustrates the effect of these statements on a 
relocatable list of lists. The first READ statement obtains 
the location of the next logical record (HEAD BODY _ 
RECORD) in the input buffer associated with INFILE and | 
assigns the location to RECORD POINTER. The head and 
body of the list are then assigned to OHEAD and 
B—>BODY. The second READ statement obtains the 
address of the next logical record (DATA_AREA) in the 


input buffer and assigns the address to RECORD _ 


POINTER. The data area is then moved from the buffer to 


-D—>DATA_ AREA. 


Self-Defining Records 


So far, the LOCATE and READ statements have been 
restricted to fixed-length records, but it is also possible to 
apply these statements to self-defining records. Such re- 
cords contain a specification of their own size, which per- 
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Figure 1.10. How a relocatable list of lists is retrieved as two logical records from a file 


mits them to vary in length. They prove useful in handling 
the varying storage requirements associated with list- 
processing techniques. 

The declaration of a self-defining record must be made 
with a based structure that contains an adjustable string 
length, adjustable area size, or adjustable array bound, the 
value of which is maintained by a variable within the struc- 
ture. This variable , however, cannot possess a value until 
storage has been allocated for the containing based struc- 
ture; otherwise, there would be no storage to hold the value 
' of the variable. Since the amount of storage to be allocated 
depends on the value of this variable, a facility is needed for 
associating a value with the veriable before allocation. 

PL/I provides this facility through the REFER option, 
which has the following general format: 


element-variable REFER(element-variable) 


Both element variables in the option must be unsubscripted 
fixed-point binary variables having the same precision. The 
variable to the right of the keyword REFER must be an 
element of the self-defining based structure, but the vari- 
able to the left must be declared outside the structure. The 
option itself must appear as a string length, area size, or 
array bound within the structure. As an example, consider 
the following DECLARE statement: 


DECLARE 


DUMMY_BODY AREA BASED (DUMMY _ POINTER), 


BINARY BODY SIZE FIXED BINARY(16,0), 
1 LIST RECORD BASED (RECORD POINTER), 
2 R_ HEAD OFFSET(DUMMY BODY), 
2 R_ BODY SIZE FIXED BINARY(16,0), 
2 R_BODY AREA(BINARY_ BODY_ SIZE 
REFER(R_BODY_SIZE)); 


LIST RECORD is declared to be a self-defining based 
structure, which contains three components: R- HEAD, 
R_BODY _ SIZE, and R_ BODY. This declaration can be 
used to generate a self-defining record for a relocatable data 
list, in which R_ HEAD serves as the offset head of the list 
and R_ BODY contains the relocatable components of the 
list. The area attribute for R- BODY uses a REFER ppuem 
to specify the size of the area: 


BINARY BODY SIZE REFER 
(R_BODY~ SIZE) 


When storage is allocated for LIST_RECORD, the size of 
R_ BODY is obtained from BINARY BODY _ SIZE (which 
is declared outside LIST RECORD) and is automatically 
assigned to R_ BODY _SIZE (which is declared inside LIST 
_ RECORD). It is the programmer’s responsibility to assign 
the proper value to BINARY BODY _SIZE before storage 


is allocated for LIST_ RECORD. By changing the value of 
BINARY BODY_ SIZE, the programmer can vary the size 
of R_ BODY within each generation of LIST RECORD. 

The following example shows how LIST RECORD may 
acquire different lengths when used to write two relocat- 
able data lists into a file: 


DECLARE 
OHEAD1 OFFSET(BODY1), 
BODY1 AREA(500) BASED(B), 
OHEAD2 OFFSET(BODY2), 
BODY2 AREA(750) BASED(B), 
DUMMY BODY AREA BASED(DUMMY POINTER), 
BINARY BODY SIZE FIXED BINARY(16,0), 
OUTFILE FILE RECORD OUTPUT, 
1 LIST RECORD BASED(RECORD POINTER), 
2 R_HEAD OFFSET(DUMMY_BODY), 
2 R_BODY_SIZE FIXED.BINARY(16,0), 
2 R_BODY AREA(BINARY_BODY_ SIZE 
REFER(R_BODY_SIZE)): 


BINARY BODY SIZE = 500; 
LOCATE LIST RECORD 
FILE(OUTFILE) SET(RECORD_ POINTER): 
DUMMY _ POINTER = ADDR 
(RECORD_POINTER—>R_ BODY); 
RECORD _POINTER—>R_HEAD = OHEAD!1; 
RECORD POINTER—>R_BODY = B—>BODY1; 


BINARY BODY SIZE = 750; 
LOCATE LIST_ RECORD 

FILE(OUTFILE) SET(RECORD_ POINTER); 
DUMMY _ POINTER = ADDR 

(RECORD _POINTER—>R_ BODY); 
RECORD POINTER—>R_HEAD = OHEAD?; 
RECORD POINTER—>R_BODY = B—>BODY?: 


: OHEADI and B—>BODY1 form the offset head and body 


area of the first list, while OHEAD2 and B—>BODY?2 serve 
as the corresponding parts of the second list. The two body 
areas have different storage sizes: BODY1 contains 500 
bytes, and BODY2 contains 750 bytes. Before the first list 
is transmitted to OUTFILE, the value 500 is assigned to 
BINARY BODY _ SIZE. Execution of the LOCATE state- 
ment for LIST RECORD causes 500 bytes of buffer 
storage to be allocated for R- BODY within LIST 
_RECORD and this size to be assigned automatically to 
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R_ BODY _ SIZE. The following statements then fill LIST 
_RECORD with the offset head and body area of the first 
list: 


RECORD POINTER—>R_HEAD = OHEAD!1; 
RECORD POINTER—>R_BODY = B—>BODY 1; 


The same process is used to write the second list into 
OUTFILE, but BINARY BODY_ SIZE is set equal to-750 
before storage is allocated for LIST_RECORD. This value 
causes the size of area R_ BODY to hate’ from 500 bytes 
to 750 bytes. 

Retrieval of these two lists is illustrated by the following 
example: 


DECLARE | 
OHEAD1 OFFSET(BODY1), 
BODY1 AREA(500) BASED(B), 
OHEAD2 OFFSET(BODY?2), » 
BODY2 AREA(750) BASED(B), 
DUMMY_ BODY AREA BASED(DUMMY POINTER), 
BINARY BODY_ SIZE FIXED BINARY(16,0), 
(BODY_SIZE1, BODY_SIZE2) FIXED DECIMAL(5), 
INFILE FILE RECORD INPUT, 
- 1 LIST RECORD BASED(RECORD_ POINTER), 
2 R_HEAD OFFSET(DUMMY _ BODY), 
2 R_BODY_ SIZE FIXED BINARY(16,0), 
2 R_BODY AREA(BINARY_ BODY_ SIZE 
REFER(R_BODY_SIZE)); 


READ FILE(INFILE) SET(RECORD_POINTER); 

DUMMY POINTER = ADDR 
(RECORD_POINTER—>R_ BODY); 

OHEAD1 = RECORD POINTER—>R_HEAD; 

B—>BODY1 = RECORD_POINTER—>R_BODY; 

BODY _SIZE1 = RECORD POINTER—> 
R_BODY_SIZE; 


The first READ statement retrieves a logical record from 
INFILE and assigns the location of the record to RECORD 
_ POINTER. This assignment causes the based structure 
LIST -RECORD to be overlaid on the record. The example 
assumes that the retrieved record contains the offset head, 
body size, and body area for a relocatable data list that is to 
be assigned to OHEAD1 and B—>BODY1. 

The REFER option in LIST_RECORD indicates that 
the size of area R_ BODY can vary and is automatically 
determined by the value of R_ BODY _SIZE. Execution of 
the following statements causes the head and body of the 
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retrieved list to be assigned to OHEAD1 and B—>BODY!1: 


OHEAD1 = RECORD POINTER—>R_HEAD; 
B—>BODY1 = RECORD _POINTER—>R_ BODY: 


Note that, although BINARY BODY _SIZE appears at the 
left of the REFER option, its value is not used or changed 
in any way by the READ statement. Only a LOCATE state- 
ment could make use of BINARY _BODY_ SIZE. In this | 
example, the size of the first retrieved body area is assigned, 
for further use, to the variable BODY _SIZE1 by the state- 
ment: 


- BODY_SIZE1 = RECORD POINTER—> 
R_BODY SIZE; 


Similar steps are used to read the next relocatable data 
list from INFILE and to assign it to OHEAD2 and 
B—>BODY?. The size of the body area for this second list 
is assigned to BODY _SIZE2. 

PL/I(F) allows one REFER option in the declaration of 
a self-defining based structure. When the REFER option 


specifies a string length or an area size, the string or area 


must be an element variable and must be the last element in 
the structure declaration. If the REFER option appears as 
an array bound, the bound must be the upper bound of the 
leftmost dimension in the array declaration, and the 
REFER option must also belong to the last array variable in 
the self-defining structure or to a minor structure that con- 
tains the last element of the self-defining structure. 

Earlier examples, illustrated in Figures 1.8 and 1.10, 
showed how to write and read body areas and data areas as 
separate logical records that are not self-defining. The fol- 
lowing discussion shows how those examples can be modi- 
fied to handle self-defining records. Consider the following 
example: | 


DECLARE 

OHEAD1 OFFSET(BODY1) 
BODY1 AREA(500) BASED(B), 
DATA1 AREA(1000) BASED(D), 
OHEAD2 OFFSET(BODY2), 
BODY2 AREA(750) BASED(B), 
DATA2 AREA(1000) BASED(D), 
DUMMY BODY AREA BASED(DUMMY POINTER), 
BINARY SIZE FIXED BINARY(16,0), 
OUTFILE FILE RECORD OUTPUT, 
1 HEAD. BODY RECORD BASED 

(RECORD_ POINTER), 

2 R_HEAD OFFSET(DUMMY_ BODY), 

2 R_BODY_SIZE FIXED BINARY(16,0), 

2 R_BODY AREA | 

(BINARY_SIZE REFER(R_BODY SIZE), 

1 DATA_RECORD BASED(RECORD_POINTER), 


2 R_DATA SIZE FIXED BINARY(16,0), 

2 PAD CHARACTER(4), 

2 R_DATA AREA(BINARY_SIZE 
REFER(R_DATA_ SIZE)); 


BINARY _ SIZE = 500; 

LOCATE HEAD. BODY RECORD 
FILE(OUTFILE) SET(RECORD_POINTER); 

DUMMY POINTER = ADDR 
(RECORD_POINTER—>R_BODY); 

RECORD _POINTER—>R_HEAD = OHEAD!1; 

RECORD POINTER—>R_ BODY = B->BODY1; 


BINARY _ SIZE = 1000; 
LOCATE DATA_RECORD 

FILE(OUTFILE) SET(RECORD_POINTER); 
RECORD POINTER—>R_DATA = D-—>DATAI; 


BINARY_SIZE = 750; 
LOCATE HEAD BODY RECORD 
FILE(OUTFILE) SET(RECORD_ POINTER); 
DUMMY POINTER = ADDR 
(RECORD _POINTER—>R_BODY); 
RECORD POINTER—>R_HEAD = OHEAD?2; 
RECORD POINTER->R_BODY = B—>BODY?2; 


BINARY SIZE = 1000; 
LOCATE DATA RECORD 

FILE(OUTFILE) SET(RECORD_ POINTER); 
RECORD POINTER—>R_DATA = D—>DATA2; 


This example applies to relocatable pointer lists and lists of 
lists. It uses the self-defining based structure HEAD _ 
BODY RECORD for the offset head and body area of 
each list, and the self-defining based structure DATA _ 
RECORD for the data area. Two lists are written. The 
offset head, body area, and data area of the first list are 
specified by OHEAD1, BODY1, and DATA1, while 
OHEAD2, BODY2, and DATA2 denote the corresponding 
parts of the second list. BODY1 and DATA1 contain 500 
and 1000 bytes each, and BODY2 and DATA2 contain 750 
and 1000 bytes each. These sizes are transmitted with the 
associated self-defining records. 


Retrieval of these two lists is illustrated by the following 


example: 


DECLARE 
OHEAD1 OFFSET(BODY1), 
BODY1 AREA(500) BASED(B), 
DATA1 AREA(1000) BASED(D), 
OHEAD2 OFFSET(BODY2), 
BODY2 AREA(750) BASED(B), 
DATA2 AREA(1000) BASED(D), | 
DUMMY BODY AREA BASED(DUMMY_ POINTER), 
BINARY SIZE FIXED BINARY(16,0), 
(SIZE1, SIZE2, SIZE3, SIZE4) FIXED DECIMAL(5), 
INFILE FILE RECORD INPUT, 
1 HEAD BODY RECORD BASED 
(RECORD_POINTER), 
2 R_HEAD OFFSET(DUMMY_ BODY), 
2 R_BODY SIZE FIXED BINARY(16,0), 
2 R_ BODY AREA(BINARY SIZE REFER 
(R_BODY_SIZE)), 
1 DATA RECORD BASED(RECORD_ POINTER), 
2 R_DATA_SIZE FIXED BINARY(16,0), 
2 PAD CHARACTER(4), 
- 2 R_DATA AREA(BINARY SIZE REFER 
- (R_DATA SIZE)); 


READ FILE(INFILE) SET(RECORD_ POINTER); 
DUMMY POINTER = ADDR | 
(RECORD_POINTER—>R_ BODY); | 
OHEAD1 = RECORD POINTER—>R_ HEAD; 
B—>BODY1 = RECORD POINTER->R_BODY; 
SIZE1 = RECORD POINTER—>R_BODY SIZE: 


READ FILE(INFILE) SET(RECORD_ POINTER); 
D—>DATA1 = RECORD _POINTER—>R_DATA; 
SIZE2 = RECORD _POINTER—>R_DATA SIZE: 


READ FILE(INFILE) SET(RECORD POINTER); 
DUMMY _ POINTER = ADDR 

(RECORD _POINTER—>R_ BODY); 
OHEAD2 = RECORD POINTER—>R_ HEAD; 
B—>BODY2 = RECORD POINTER—>R_ BODY; 
SIZE3 = RECORD _POINTER—>R_BODY_ SIZE; 


Re 


READ FILE(INFILE) SET(RECORD_ POINTER); 
D—>DATA2 = RECORD POINTER—>R_ DATA; 
SIZE4 = RECORD POINTER—>R_BODY_ SIZE; 
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This example uses the same self-defining based structure 
HEAD BODY RECORD and DATA RECORD as the 
preceding example. It retrieves two lists. The parts of the 
first list are assigned to OHEAD1, BODY1, and DATA, 
and those of the second list are assigned to OHEAD?2, 
BODY?2, and DATA2. The sizes of BODY1 and DATAI are 
assigned to SIZE1 and SIZE2 for possible use by other 
statements. SIZE3 and SIZE4 receive the sizes of BODY2 
and DATA2.. 
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Chapter 2. Processing Relocatable Lists 


The following discussion develop subroutines that use the 
relocation facilities described in the preceding chapter. No 
attempt is made, however, at creating a collection of proce- 
dures for relocatable lists. Instead, it is assumed that lists 
will usually be created and manipulated in absolute form 


and then converted to relocatable form when they are to be | 


moved to new locations or transmitted to files. This 
approach restricts the procedures needed for relocatable 
lists to five categories: 


1. Converting absolute lists to relocatable form 
2. Converting relocatable lists to absolute form 
3. Moving relocatable lists 

4. Writing relocatable lists 

5. Reading relocatable lists 


Each category contains subroutines for three types of lists: 
data lists, pointer lists, and lists of lists. 


B->BODY_AREA 


The subroutines in these categories are designed to 
process an arbitray number of relocatable lists in each area 
and are not limited to areas that contain a single list. The 
heads of all the relocatable lists in an area are passed to 
each subroutine as an array of offset variables. This con- 
vention permits the number of offset heads in the array 
(and consequently, the number of lists in the area) to vary 
while at the same time allowing the number of arguments in 
each invocation to remain constant. As an example, Figure 
2.1 shows the area B->BODY_ AREA with three relocat- 
able data lists, the heads of which are individual offset 
variables. The offset head OAVAIL is assumed to identify 
the relocatable list of available storage components in the 
area. The same area and lists appear in Figure 2.2, but the 
offset heads of the lists have been assigned to the array 
OHEAD_ ARRAY. The subroutines in the following dis- 
cussions assume an arbitrary size for the array of offset 
heads and transmit the array as a self-defining record. 





Figure 2.1. Relocatable lists with individual offset heads 
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B-> BODY_AREA 





Figure 2.2. Relocatable lists with their offset heads stored in an array 


CONVERTING ABSOLUTE LISTS 
TO RELOCATABLE FORM 


The following discussions develop three subroutines for 
converting the absolute lists in one area to relocatable lists 
in another area: 


1. CON_DAR, which converts data lists from absolute 
to relocatable form 

2. CON PAR, which converts pointer lists from 
absolute to relocatable form 

3. CON_LAR, which converts lists of lists from 
absolute to relocatable form 


CON_DAR Subroutine 


Purpose 


To convert data lists from absolute to relocatable 
form 


Reference 


CON_DAR(BODY_AREA1, HEAD_ ARRAY, 
BODY_AREA2, OHEAD_ ARRAY) 


Entry-Name Declaration 


DECLARE CON_DAR 
ENTRY(AREA(*),(*)POINTER, AREA(*), 
(*)OFFSET(DUMMY_BODY_AREA)); 


Meaning of Arguments 


— the area that contains the 
bodies of the absolute lists 
being converted to relocatable 
form 


BODY_AREA1 


HEAD _ARRAY ~ — the array that contains the 
pointer heads of the absolute 


lists in BODY_AREA1 


These subroutines are used after the absolute lists have 
been constructed and processed by other routines and are 
ready to be moved to new storage locations or to be written 
into files. 


CON_DAR Subroutine 


Figures 2.3A and 2.3B present the CON DAR subroutine, 
which converts absolute data lists in one area to relocatable 
data lists in another area. The subroutine uses four argu- 
ments: the body area and head array of the absolute data 
lists being converted, and the body area and head array that 
are to receive the relocatable data lists during conversion. 


— the area that receives the 
bodies of the lists after they 
have been converted to 
relocatable form 


BODY_AREA2 


OHEAD ARRAY -— the array that receives the 
offset heads of the relocatable 


lists in BODY AREA2 
Remarks 


BODY _AREA1 and BODY _AREA2 can have any 
storage class and be of arbitrary and unequal size. If 
BODY_AREA2 is not large enough to receive the 
converted components of BODY_ AREA, or if 
OHEAD_ARRAY is smaller than HEAD_ARRAY, 
or if HEAD _ ARRAY is completely null, then 
OHEAD_ARRAY is filled with null offset values, 
and the content of BODY _AREA2 becomes 
undefined. 


Other Programmer-Defined Procedures Required 


None 


| Method 


Each absolute list in BODY AREAT is reconstructed, 
component by component, as a relocatable list in 
BODY AREA2. The data element of each 
component is a single character. 


Figure 2.3A. Description of the CON_DAR subroutine for converting data lists from absolute to relocatable form 
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CON_DAR: | 
PROCEDURE (BODY_AREA1, HEAD_ARRAY, 
BODY_AREA2, OHEAD_ARRAY); 
DECLARE 
(DUMMY_POINTER,C1,C2)PCINTER, 
(BODY_AREA1, BODY_AREA2) AREA(*), 
DUMMY_BODY_AREA BASED 
(DUMMY_POINTER) AREA, 
(HEAD_ARRAY(*), SAVE) POINTER, 
OHEAD_ARRAY(*) OFFSET 
(DUMMY_BODY_AREA), 
COMPONENT] BASED(C1), 
DATA CHARACTER(1), 
LINK POINTER, 
CCMPONENT2 BASED(C2), 
DATA CHARACTER(1)> 
OLINK OFFSET(DUMMY_BODY_AREA) $ 
/* IF AREA CONDITION OCCURS, | 
BODY_AREA2 IS TCO SMALL TO RECEIVE 
CONTENTS OF BODY_AREA1. GO TO 
NULL_LIST.¥*/ 
ON AREA 
GO TO 
NULL_LISTS; 
/* IF OQHEAD_ARRAY IS SMALLER THAN 
HEAD_ARRAY, GO TO NULL_LIST */ 


NN & NM PA 


IF 
DIM(OHEAD_ARRAY»1)<DIM(HEAD_ARRAY, 1) 
THEN 
GO TO 
NULL_LIST3 | 
/* ASSOCIATE OFFSETS QHEAD_ARRAY AND 
OLINK WITH BODY_AREA2.*/ 
DUMMY_POINTER = ADDR(BODY_AREA2); 
/* CCNVERT SUCCESSIVE DATA LISTS IN 
BODY_AREA1 TO RELOCATABLE DATA LISTS 
IN BODY_AREA2.*/ 
J=LBOUND (OQHEAD_ARRAY,1)-13 
BEGIN_CCNVERT_LOOP: 


DO 
I=LBOUND(HEAD_ARRAY,1) TO HBOUND 
CHEAD_ARRAY,1)3 
J = Jl; 
4* IF I-TH POINTER IN HEAD_ARRAY IS 
NULL» SET J-TH OFFSET IN QHEAD_ARRAY 
TO NULLO, AND CONVERT NEXT LIST IN 
BODY_AREA1.*/ 
IF : 
HEAD_LARRAY(I) = NULL 
THEN 
DO; 


OHEAD_ARRAY(J) = NULLO$ 


GO To 
END_CONVERT_LCOP; 
END; | 
/* ALLOCATE COMPONENT2 IN 
BODY_AREA2, AND ASSIGN TO THE 
ALLOCATION THE DATA VALUE OF THE 
FIRST COMPONENT IN THE I-TH LIST IN 
BODY_AREAL.*/ 
ALLOCATE COMPONENT2. IN(BODY_AREA2) 
SET(C2)3 
OHEAD_ARRAY(J), SAVE = C23 
C1 = HEAD_ARRAY(I)3 
C2—>COMPONENT2.DATA = Cl1-> 
COMPONENT1.DATA; 
/* PERFORM SUCCESSIVE ALLOCATIONS OF 
COMPONENT2 IN BODY_AREAl, AND ASSIGN 
TO THE ALLOCATIONS THE DATA VALUE OF 
SUCCESSIVE COMPONENTS IN THE I-TH 
LIST WITHIN BODY_AREA1.*/ 
Cl = C1->LINK; 
po 
WHILE (C1-+=NULL); 
ALLOCATE COMPONENT2 IN (BODY_AREA2) 
SET(C2)3 | 
SAVE->OLINK, SAVE = C23 
C2—>COMPONENT2.DATA = C1-> 
COMPONENT1.DATA3 
Cl = C1->LINK3 
END; | 
| /* ASSIGN A NULL OFFSET VALUE TO 
OLINK IN LAST COMPONENT OF J-TH LIST 
IN BODY_AREA2.*/ | 
SAVE->OLINK = NULLO; : 
/* CONVERT NEXT LIST IN BODY_AREA1 
BY EXECUTING NEXT CYCLE OF CONVERT 
LOOP.*/ 
END_CONVERT_LOOP: 
END; 
/* THIS POINT IS REACHED WHEN ALL. 
DATA LISTS IN BODY_AREA1 HAVE BEEN 
CONVERTED TO RELOCATABLE DATA LISTS 
IN BODY_AREA2. THEREFORE, RETURN 
SUBROUTINE CONTROL TO POINT OF 
INVOCATION. */ 
RETURN; 
/* IF THIS POINT IS REACHED, ASSIGN 
A NULL OFFSET VALUE TO EACH ELEMENT 
OF OHEAD_ARRAY.*/ 
NULL_LIST: 
| OHEAD_ARRAY = NULLO; 
END 
CON_DAR; 


Figure 2.3B. The CON DAR subroutine used to convert data lists from absolute to relocatable form 
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CON_PAR Subroutine 


Figures 2.4A and 2.4B present the CON_PAR subroutine, 
which converts absolute pointer lists to relocatable form. 
The subroutine uses five arguments: the body area and head 
array of the absolute pointer lists being converted, the body 
area and head array that are to receive the relocatable 
pointer lists during coriversion, and the data area, which is 
shared by both the absolute and relocatable forms of the 
pointer lists. 


CON_PAR Subroutine BODY AREA2 — the area that receives the 

| bodies of the lists after they 
have been converted to 

Purpose relocatable form 

To convert pointer lists from absolute to relocatable OHEAD_ ARRAY — the array that receives the 

form offset heads of the relocatable 


lists in BODY_AREA2 


Reference DATA_AREA — the area that contains the 
| data values of the lists before 
CON_PAR (BODY_AREA1, HEAD_ARRAY and after conversion 
BODY_AREA2, OHEAD_ARRAY, 
DATA_AREA) Remarks 


BODY _AREA1, BODY_AREA2, and DATA_AREA 
can have any storage class and be of arbitrary size. 


Entry-Name Declaration 


DECLARE CON_PAR : 
ENTRY(AREA(*), (*) POINTER, 
AREA(*), (*) OFFSET 
(DUMMY_BODY_AREA), AREA(*)); 


Meaning of Arguments 


BODY AREAT1 — the area that contains the 
bodies of the absolute lists 
being converted to relocatable 
form 

HEAD ARRAY ~~ — the array that contains the 


pointer heads of the absolute 
lists in BODY _AREAT1 


If BODY AREA2 is not large enough to receive the 
converted components of BODY AREA, or if 
OHEAD_ARRAY is smaller than HEAD ARRAY, 
or if HEAD ARRAY is completely null, then 
OHEAD_ARRAY is filled with null offset values, 
and the content of BODY _AREA2 becomes 
undefined. 


Other Programmer-Defined Procedures Required 


None 


‘Method 


Each absolute list in BODY AREA is reconstructed, 
component by component, as are relocatable lists in 


BODY AREA2. After conversion, both types of 


lists share DATA_ AREA. 


Figure 2.4A. Description of the CON_PAR subroutine for converting pointer lists from absolute to relocatable form 
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CON_PAR?: 


DECLARE 
-(BODY_AREAl, BODY_AREA2, 


po I 


IF HEAD_ARRAY(I) == 


PROCEDURE(BCDY_AREA1l, HEAD_ARRAY, 
BODY_AREA2, OQHEAD_ARRAY +, 
DAT A_ AREA); 


DATA_AREA) 
AREA(*), 

DUMMY_BODY_AREA BASED(DUMMY_ POINTER1L) 
AREA, 

DUMMY_DATA_AREA BASED(DUMMY_POINTER2) 
AREA, ~~ 
(HEAD_ARRAY(*), 
OHEAD_ARRAY (*) 
OFFSET(DUMMY_BODY_AREA), 
COMPONENT1 BASED(C1), 

DATA POINTER, 
LINK POINTER, 

COMPONENT2 BASED(C2), 

ODATA OFFSET ( OUMMY_. DATA_AREA), 
CLINK OFFSET(OUMMY_DATA_AREA) 3 
/* IF AREA CONDITION OCCURS, . 
BODY_AREA2 IS TOO SMALL TO 
RECEIVE CONTENTS OF BODY_AREA1]. GO 
TO NULL_LIST. */ 
ON AREA 

TO 

NULL_LISTS$ 

4* IF HEAD_ARRAY IS NULL, 
NULL_LIST. *#/ 

LBCUND (HEAD_ARRAY,1) 

TO HBOUND(HEAD_ARRAY »91)3 
NULL 


SAVE) POINTER,» 


NM NM em — RP eH 


GC TC 


_ THEN GO TO GO2; 


END; 


G02: 


IF 


THEN 


GO TO 
~ NULL_LIST; 


/* IF CHEAD_ARRAY IS SMALLER THAN 
HEAD_ARRAY, GO TO NULL_LIST. */ 


DIM(OHEAD_ARRAY»1)<DIM(HEAD_ARRAY, 1) 


TO 

NULL_LIST3$ 

/* ASSOCIATE OFFSETS QHEAD_ARRAY AND 
OLINK WITH BODY_AREA2 AND OFFSET 
ODATA WITH DATA_AREA. */ 
DUMMY_POINTER1 = ADOR(BODY_AREA2); 
DUMMY_POINTER2 = ADDR(DATA_AREA); 
/* CONVERT SUCCESSIVE POINTER LISTS 
IN BODY_AREA1 TO RELOCATABLE 
POINTER LISTS IN BODY_AREA2. */ 

J = LBOUND(OQHEAD_ARRAY,1)-13 


BEGIN_CONVERT_LOOP: 


DO 


IF 


I = LBOUND(HEAD_ARRAY»1) 

TO HBOUND(HEAD_ARRAY,»1)3 

J=zaJ +15 

f* IF I-TH POINTER IN HEAD_ARRAY IS 
NULL,» SET J-TH OFFSET IN OHEAD _ARRAY 
TO NULLC, AND CONVERT NEXT LIST IN 
BODY_AREA1]. */ 


HEAD_LARRAY(T) = NULL 


END; 


I 


DO 


I 


END; 


THEN 
DO; 


9 


GO 


F 
THEN 


ELSE 


OHEAD_ARRAY(J) = 


NULLO; 
TO | 
END_CONVERT_LOOP; 


4* ALLOCATE COMPONENT2 IN 
BODY_AREA2, AND ASSIGN TO THE 
ALLOCATION THE DATA POINTER OF THE 
FIRST COMPONENT IN THE I-TH LIST IN 
BODY_AREAL. */ 

ALLOCATE COMPONENT2 IN(BODY_ AREA2) 
SET(C2)3$ 
OHEAD_ARRAY(J)>» 
Cl = 


SAVE = C23 
HEAD_ARRAY (1); 


DATA = NULL 


ODATA = NULLC; 
ODATA = DATA; 
/* PERFORM SUCCESSIVE ALLOCATIONS 
OF COMPONENT2 IN BODY_AREA2, AND 


ASSIGN TO THE ALLOCATIONS THE DATA 


F 


THEN 


POINTER OF SUCCESSIVE COMPONENTS IN 
THE I-TH LIST WITHIN BODY_AREA1]. */ 
Cl = C1->LINK; 


WHILE(C17=NULL) $5 

ALLOCATE COMPONENT2 IN(BODY_AREA2) 
SET(C2)3 — 

SAVE->OLINK,SAVE = C2; 


ELSE 


DATA = NULL 
ODATA = NULLO$ 
ODATA = DATA; 
Cl = C1l->LINK; 


/* ASSIGN A NULL OFFSET VALUE TC 
OLINK IN LAST COMPONENT OF J-TH LIST 


IN BODY_AREA2. */ 


SAVE->OLINK = NULLO3 

4* CONVERT NEXT LIST IN BODY_AREAL 
BY EXECUTING NEXT CYCLE OF CONVERT 
LOOP. */ 


END_CONVERT_LOOP: 


END; 


END 


/* THIS POINT IS REACHED WHEN ALL 
POINTER LISTS IN BOOY_AREA1] HAVE 
BEEN CONVERTED TO RELOCATABLE 
POINTER LISTS IN BODY_AREA2, 
THEREFORE, RETURN SUBROUTINE CONTROL 
TO POINT OF INVOCATION. */ | 
RETURN; 

/* IF THIS POINT IS REACHED, ASSIGN 
A NULL OFFSET VALUE TO EACH ELEMENT 
OF OHEAD_ARRAY. ¥*/ 


NULL_LIST: 


OHEAD_ARRAY = NULLO; 


CON_PAR 3; 


Figure 2.4B. The CON PAR subroutine used to convert absolute pointer lists to relocatable form 
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CON_LAR Subroutine 


Figures 2.5A and 2.5B present the CON_LAR subroutine, 
which converts absolute lists of lists to relocatable form. 
The subroutine uses six arguments: the body area and head 
array of the absolute lists of lists being converted, the body 
area and head array that are to receive the relocatable lists 
of lists during conversion, the data area, which is shared by 


CON_LAR Subroutine 
Purpose 


To convert lists of lists from absolute to relocatable 
form 


Reference 


CON_LAR(BODY_AREA1,HEAD_ ARRAY, 
BODY_AREA2, OHEAD_ ARRAY, 
DATA_AREA,#SUBS) 


Entry-Name Declaration 
DECLARE CON_LAR 


ENTRY(AREA(*), (*)POINTER, 
AREA(*), (*)OFFSET 


(DUMMY_BODY_AREA), AREA(*), - 


FIXED DECIMAL); 
Meaning of Arguments 


_-— the area that contains the 
bodies of the absolute lists 
being converted to relocatable 
form 


BODY_AREA1 


— the array that contains the 
pointer heads of the absolute 
lists in BODY _AREAT 


HEAD_ ARRAY 


BODY AREA2 — the area that receives the 
bodies of the lists after they 
have been converted to 


relocatable form 


both the absolute and relocatable forms of the lists of lists, 
and the number of sublists. | 

The code in CON_ LAR indicates an optional use of the 
recursive function procedure CONV shown in the 
Appendix. CONV examines the type code in each list com- 
ponent and takes appropriate conversion action. CONV 
returns an offset value. | 


OHEAD_ARRAY_ — the array that receives the 
offset heads of the relocatable 


lists in BODY_AREA2 


DATA_AREA 


— the area that contains the 
data values of the lists before 
and after conversion 

#SUBS — the number of sublists 
Remarks 


- BODY_AREA1, BODY_AREA2, and DATA_ AREA 
can have any storage class and be of arbitrary size. 
If BODY_AREA2 is not large enough to receive the 
converted components of BODY_AREA‘1, or if 
OHEAD_ARRAY is smaller than HEAD_ARRAY, 
or if HEAD ARRAY is completely null, then 
OHEAD_ ARRAY is filled with null offset values, 
and the content of BODY_AREA2 becomes 
undefined. 


Other Programmer-Defined Procedures Required 


CONV (optional) 


Method 


Each absolute list in BODY AREA‘ is reconstructed, 
component by component, as a relocatable list in 
BODY AREA2. After conversion, both types of 
lists share DATA. AREA. 


Figure 2.5A. Description of the CON_LAR subroutine for converting lists of lists from absolute to relocatable form 
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CON_LAR: 
a | PROCEDURE ( BODY_ AREAL gHEAD_ ARRAY» 
BODY_AREA2, OHEAD_ARRAY» DATA_AREA, 
#SUBS)3 . 
DECLARE 
#SUBS FIXED DECIMAL, 
(SAVE, KEEP, PAC #SUBS)) POINTER; 
/* PARAMETER #SUBS IS NOT NECESSARY > 
WHEN FUNCTION CONV IS USED */ 
(DUMMY_BODY_POINTER,» 
DUMMY_DATA_POINTER»C1,C2)POINTER, 
(BODY_AREA1 » BODY_AREA2,DATA_AREA) 
AREA(*#), 
DUMMY_BODY_AREA 
BASED(OUMMY_BODY_POINTER) AREA, 
DUMMY_DATA_AREA 
BASED(DUMMY_DATA_POINTER) AREA, 
HEAD_ARRAY(*) POINTER, 
OHEAD_ARRAY(*) 
OFFSET (DUMMY_BODY_AREA)» 
COMPONENTI BASED(C1), 
TYPE CHARACTER(1), 
VALUE POINTER, 
LINK POINTER, 
D_COMPONENT2 BASED(C2), 
D_OTYPE CHARACTER(1), 
D_OVALUE OFFSET(DUMMY_DATA_AREA), 
D_OLINK OFFSET(DUMMY_BODY_AREA), 
L_COMPONENT2 BASED(C2), 
L_OTYPE CHARACTER(1), 
L_OVALUE OFFSET(DUMMY_BODY_AREA), 
L_OLINK OFFSET(OUMMY_BODY_AREA) ; 
/* IF AREA CONDITION OCCURS, 
BODY_AREA2 IS TOO SMALL TO RECEIVE 
CONTENTS OF BODY_AREAL. GO TO 
NULL_LIST. */ 
ON AREA 
GO TO 
NULL_LIST3 | 
/* IF QHEAD_ARRAY IS SMALLER THAN 
HEAD_ARRAY, GO TO NULL_LIST. */ 


MN NY & MN A =e — PY A = 


IF 
DIM(QHEAD_ARRAY,1)<DIM(HEAD_ARRAY, 1) 
THEN : 
GO TO 

NULL_LIST$ 

7* ASSOCIATE OFFSETS QHEAD_ARRAY, 

D_OLINK, L_OLINK, AND L_OVALUE WITH 

BODY_AREA2, AND OFFSET O_OVALUE WITH 

DATA_AREA. */ 

DUMMY_BODY_POINTER = 

ADDR (BODY_AREA2)$ 

DUMMY_DATA_POINTER = 

ADDR(DATA_AREA)$ 

/* CONVERT SUCCESSIVE LISTS OF 

LISTS IN BODY_AREA1 TO 

RELOCATABLE LISTS OF LISTS IN 

BODY_AREA2. */ 

PA = NULL 5 

J = LBOUND(OHEAD_ ARRAY, 1)- 1; 
BEGIN_CONVERT_LOOP: 

DO 

I = LBOUND(HEAD_ARRAY,1) 
TO HBOUND(HEAD_ARRAY,1)3 
J=J54+13 
K = 


Cl = HEAD_ ARRAY(1T)$ 

IF Cl = NULL THEN OO; 
OHEAD_ARRAY(J) = NULLO; 
GO TO END_ CONVERT ~LOOP; 
END; 


/* OPTION */ 
/* TEST */ IF #SUBS 7= 1 THEN GO TO NO_CONV; 
_ USE_CONV: 

/* USE THE FOLLOWING CODE 
TO EMPLOY FUNCTION CONV 
FOR CONVERSIONS */ 
QHEAD_ARRAY(J) = CONV(HEAD_ARRAY(I), 
BODY_AREAl, BODY_AREA2, DATA_AREA)3 
GO TO END_CONVERT_LOOP; 


ys END OF OPTION */ 


NO_CONV: 
ALLOCATE L_ COMPONENT2 IN(BODY_ AREA2) 
SET(C2)3 
SAVE, KEEP, OHEAD_ARRAY(J) = C23 
C2->L_OTYPE = "L*;5 | 
PA(K) = C1->VALUE; 
Cl = Cl-SLINKS 
DO WHILE(C1 -= NULL) 


K = K + 1s 

ALLOCATE L_COMPONENT2 IN(BODY_AREA2) 
SET(C2)5 

SAVE->L_OLINK = C23 

SAVE = C23 


(C2->L_OTYPE = "L*5 
PACK) = C1->VALUE; 
C1 = Cl->LINKs 


END; 

SAVE->L_OLINK = NULLO3 
D_LIST: | | 

DO L = 1 TO #SUBS; 

Cl = PA(L)s | 


IF Cl = NULL THEN GOTO END_O_ LIST; 
ALLOCATE O_COMPONENT2 IN(BODY_AREA2) 
SET(C2)5 
SAVE = C235 . 
KEEP->L_OVALUE = C23 
KEEP = KEEP—>L_OLINK; 
C2->D_OTYPE = *D*; 
IF C1->VALUE = NULL 
THEN C2->D_OVALUE 
ELSE C2->D_OVALUE 
Cl = C1l->LINKS 
DO WHILE(C1 -~= NULL); 
ALLOCATE D_COMPONENT2 ESPEN AREA2) 
SET(C2)5 
SAVE->D_OLINK = C23 
SAVE = C23 
C2->D_OTYPE = "O°; 
IF C1l->VALUE = NULL 
THEN C2->D_OVALUE = NULLOS 
ELSE C2=>0_OVALUE = C1~>VALUE$ 
Cl = Cl->LINKS 
END; 
SAVE->D_OLINK = NULLO$; 
END_O_LIST: END; 


NULLOS 
C1->VALUES 


END_CONVERT_LOOP=: 


END; ) 
/* WHEN THIS POINT IS REACHED, ALL 
LISTS OF LISTS IN BODY_AREA1] HAVE 
BEEN CONVERTED TO RELOCATABLE LISTS 
OF LISTS IN BODY_AREA2. THEREFORE, 
RETURN SUBROUTINE CONTROL TO POINT 
OF INVOCATION. */ 
RETURNS 
/* IF THIS POINT IS REACHED, ASSIGN 
A NULL OFFSET VALUE TO EACH 
ELEMENT OF OHEAD_ ARRAY. */ 
NULL_LISTs: 
OHEAD_ARRAY = NULLO;$ 


END 


CON_LAR 5 


Figure 2.5B. The CON_LAR subroutine used to convert absolute lists of lists to relocatable form 
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CONVERTING RELOCATABLE LISTS 
TO ABSOLUTE FORM 


The following discussions develop three subroutines for 
converting the relocatable lists in one area to absolute lists 
in another area: 


1. CON_DRA, which converts data lists from relocat- 
able to absolute form | 
2. CON PRA, which converts pointer lists from 
relocatable to absolute form 
3. CON LRA, which converts lists of lists from 
relocatable to absolute form 


CON_DRA Subroutine 


Purpose 


To convert data lists from relocatable to absolute 
form 


Reference 


CON_DRA(BODY_AREA1, OHEAD_ARRAY, 
BODY_AREA2, HEAD_ARRAY) 


Entry-Name Declaration 


DECLARE CON_DRA 
ENTRY(AREA(*), (*)OFFSET 
(DUMMY_BODY_AREA), AREA(*), 
(*)POINTER); 


Meaning of Arguments 
BODY_AREAT — the area that contains the 
bodies of the relocatable 
lists being converted to 
absolute form 


OHEAD ARRAY -— the array that contains the 
offset heads of the relocatable 
lists in BODY _AREA1 





These subroutines are used after the relocatable lists 
have been retrieved from files or moved to new storage 
locations. Conversion of the lists to absolute form permits 
them to be processed by routines that accept only absolute 
lists. 


CON_DRA Subroutine 


Figures 2.6A and 2.6B present the CON DRA subroutine, 
which converts data lists from relocatable to absolute form. 
The subroutine uses four arguments: the body area and 
head array of the relocatable lists being converted, and the 
body area and head array that are to receive the absolute 
lists during conversion. 






















BODY AREA2 — the area that receives the 
bodies of the lists after they 
have been converted to abso- 
lute form 

HEAD ARRAY ~ — thearray that receives the 
pointer heads of the absolute 


lists in BODY _AREA2 
Remarks 


BODY _AREA1 and BODY_AREA2 can have any 
storage class and be of arbitrary and unequal size. 

If BODY _AREA2 is not large enough to receive the 
converted components of BODY _AREA1, or if 
-HEAD_ARRAY is smaller than OHEAD_ ARRAY, 
or if all positions of OHEAD_ ARRAY contain null 
offset values, then HEAD_ARRAY is filled with null 
pointer values, and the content of BODY_AREA2 
becomes undefined. 


Other Programmer-Defined Procedures Required 
None 

Method 
Each relocatable list in BODY AR EA1 is recon- 
structed, component by component, as an absolute 


list in BODY AREA2. The data element of each 
component is a single character. 


Figure 2.6A. Description of the CON DRA subroutine for converting data lists from relocatable to absolute form 
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CON_ORAS: 


DECLARE 


IF 


THEN 
GO TO 


PROCEDURE (BODY_AREA1,»CHEAD_ARRAY, 
BODY_AREA2,HEAD_ARRAY)$ 


(DUMMY_POINTER,C1,C2) POINTER, 
(BODY_AREA1 »BODY_AREA2) AREA(*) y 
DUMMY_BODY_AREA BASED 
(DUMMY_POINTER) AREA, 
OHEAD_ARRAY(*) CFFSET 
(DUMMY_BODY_AREA)» 
(HEAD_ARRAY(#), SAVE, TEMP) POINTER, 
COMPONENTI BASED(C1)s 

DATA CHARACTER(1), 

OLINK OFFSET(OUMMY_BODY_AREA) » 
COMPONENT2 BASED(C2), 

DATA CrHARACTERiii»® 

LINK POINTER; . 

/* IF AREA CONDITION OCCURS, 


TN RO m POA) 


BODY_AREA2 IS TCO SMALL TO RECEIVE 


CONTENTS OF BODY_ AREAL. GO TO 
NULL_LIST.*/ 
ON AREA 
TO } 
NULL_LISTS 
/* IF HEAD_LARRAY IS SMALLER THAN 


OHEAD_ARRAY,», GO TO NULL_LIST.*/ 


DIM( HEAD_ARRAY,1)<DIM(QHEAD_ARRAY, 1) 


NULL_LLISTS$ 

/* ASSOCIATE OFFSETS QHEAD_ARRAY AND 
OLINK WITH BODY_AREA1.*/ 
DUMMY_POINTER = ADOR(BODY_AREAL); 

4/* CONVERT EACH RELOCATABLE DATA 
LIST IN BODY_AREA1 TO AN ABSOLUTE 
DATA LIST IN BODY_AREA2.¥*/ 

J = LBOUND(HEAD_ARRAY,1)-13 


BEGIN_CONVERT_LOOP: 


DO 


IF 


THEN 


DO; 


I = LBOUND(OHEAD_ARRAY,1) TO HBOUND 
(QHEAD_ARRAY,»1)3 

J = J413 | 

/* IF I-TH OFFSET IN QHEAD_ARRAY IS 
NULLO, SET J-TH POINTER IN 
HEAD_ARRAY TO NULL» AND. CONVERT 
LIST IN BODY_AREA1.*/ 


NEXT 
OHEAD_ARRAY(I) = NULLO 


HEAD_ARRAY(J) = NULL3 


GO TO 


END_CONVERT_LOOP; | 


END; 


I 


-HEAOD_ARRAY(J) + 


F 
THEN 


ELSE 


ENO; 


/* ALLOCATE COMPONENT2 IN 
BODY_AREA2, AND ASSIGN TO THE 
ALLCCATION THE CATA VALUE OF THE 
FIRST COMPONENT IN THE I-TH LIST IN 
BODY_AREA1.*/ 

ALLOCATE COMPONENT2 IN(BODY_AREA2) 
SET (C2)3 

SAVE = C23 
TEMP = OHEAD_ARRAY(I1)3 
C2->COMPONENT2.DATA = 
COMPONENTL.DATA$ 

/* PERFORM SUCCESSIVE ALLOCATIONS OF 
COMPONENT2 IN BODY_AREA2, AND ASSIGN 
TO THE ALLOCATIONS THE DATA VALUES 
OF SUCCESSIVE COMDONENTS IN THE [=TH 
LIST WITHIN BOOY_AREAL.*/ 

Cl = TEMP—>OLINK; | 

DO WHILE(C1 -= NULL); 

ALLOCATE COMPONENT2 IN(BODY_AREA2) 
SET(C2)3$ | 
SAVE->LINK, SAVE = C23 
C2—->COMPONENT2.DATA = 
COMPONENTL.OATAS 


TEMP-> 


C1-> 


C1->OLINK = NULLO 


Cl = NULL3$ 


Cl C1->OLINKS 


/* ASSIGN A NULL VALUE TO LINK IN 
LAST COMPONENT OF J-TH LIST IN 
BODY_AREA2.*/ ; 


SAVE->LINK = NULLS 


4% CONVERT NEXT LIST IN BODY_AREAIL 


BY EXECUTING NEXT CYCLE OF CONVERT 
LOOP.*/ 


END_CONVERT_LOOP: 


END; 
/* THIS POINT IS REACHED WHEN ALL 
RELGOCATABLE LISTS IN BODY_AREA1 
HAVE BEEN CONVERTED TO ABSOLUTE 
LISTS IN BODY_AREA2. THEREFORE, 
RETURN SUBROUTINE CONTROL TO POINT 
OF INVOCATION.*/ 
RETURNS | | 
/* IF THIS POINT IS REACHED, ASSIGN 
A NULL VALUE TO EACH ELEMENT OF 
HEAD_ARRAY.*/ 

NULL_ LIST: 
HEAD_ARRAY = NULL3 

END : 


CON_DRAS$ 


Figure 2.6B. The CON DRA subroutine used to convert data lists from relocatable to ab solute form 
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CON _PRA Subroutine 


Figures 2.7A and 2.7B present the CON_ PRA subroutine, 
which converts relocatable pointer lists to absolute form. 
The subroutine uses five arguments: the body area and head 
array of the relocatable pointer lists being converted, the 
body area and head array that are to receive the absolute 
pointer lists during conversion, and the data area, which is 
shared by both the relocatable and absolute forms of the 
pointer lists. 


CON_PRA Subroutine 


Purpose 


To convert pointer lists from relocatable to absolute 
form 


Reference 


CON_PRA(BODY_AREA1, OHEAD_ARRAY, 
BODY_AREA2, HEAD_ ARRAY, 
DATA_AREA) 


Entry-Name Declaration 


DECLARE CON_PRA 
ENTRY (AREA(*), (*)OFFSET 
(DUMMY_BODY_AREA), AREA(*), 
(*)POINTER, AREA(*)); 


Meaning of Arguments 
- BODY_AREAI1 — the area that contains the 
bodies of the relocatable 
lists being converted to 
absolute form 


OHEAD_ARRAY -— the array that contains the 
offset heads of the relocatable 
lists in BODY _ AREAI1 


BODY_AREA2 ~~ — the area that receives the 
bodies of the lists after they 
have been converted to 
absolute form 


HEAD ARRAY ~ — the array that receives the 
pointer heads of the absolute 
lists in BODY _AREA2 


DATA_AREA — the area that contains the 
data values of the lists 
before and after conversion 

Remarks 


BODY _AREA1, BODY_AREA2, and DATA_AREA 
can have any storage class and be of arbitrary size. 

If BODY_AREA2 is not large enough to receive the 
converted components of BODY_AREAT, or if 
HEAD_ARRAY is smaller than OHEAD_ ARRAY, 

or if all positions of OHEAD_ ARRAY contain 

null offset values, then HEAD ARRAY is filled with 
null pointer values, and the content of BODY_AREA2 
becomes undefined. 


Other Programmer-Defined Procedures Required 


None 


Method 


Each relocatable list in BODY_AREA‘1 is recon- 
structed, component by component, as an absolute 
list in BODY AREA2. After conversion, both types 
of lists share DATA_ AREA. 


Figure 2.7A. Description of the CON_PRA subroutine for converting pointer lists from relocatable to absolute form 
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CON_PRA: LIST IN BODY_AREA1]. */ 


PROCEDURE (BODY_AREA1, QHEAD_ARRAY, IF 


BODY_AREA2, HEAD_ARRAY, DATA_AREA)$ OHEAD_ARRAY(I) = NULLO 
DECLARE © THEN 

(BOCY_AREA1,BODY_AREA2,DATA_ AREA) DO; 

AREA(*), HEAD_ARRAY(J) = NULL3$ 

~DUMMY_BODY_AREA | GO To - 7 


BASED(DUMMY_POINTER1L) AREA, END_CONVERT_ LOOP; 


ENDs$ 


DUMMY_DATA_AREA 
BASED(DUMMY_POINTER2) AREA, /* ALLOCATE COMPONENT2 IN BCDY_AREA2, 
(HEAD_ARRAY(*), SAVE, TEMP) POINTER, AND ASSIGN TO THE ALLOCATION THE 
OHEAD_ARRAY (*) DATA POINTER OF THE FIRST COMPONENT 
OFFSET(OUMMY_BODY_AREA)»,» . IN THE I-TH LIST IN BODY_AREA] */ 
1 COMPONENT] BASED(C1)>, ALLOCATE COMPONENT2 IN(BODY_AREA2) 
2 ODATA OFFSET(OUMMY_DATA_AREA)» SET(C2)35 
2 OLINK OFFSET(OUMMY_BODY_ AREA)» HEAD_ARRAY( J), SAVE = C23 
1 CCMPONENT2 BASED(C2), TEMP = QHEAD_ARRAY(I)3 
2 DATA POINTER, C2->DATA = TEMP—>ODATA3 
2 LINK POINTERS /* PERFORM SUCCESSIVE ALLOCATIONS OF 
/* IF AREA CONDITION OCCURS, COMPONENT2 IN BODY_AREA2, AND ASSIGN 
BODY_AREA2 IS TCO SMALL TO RECEIVE TO THE ALLOCATIONS THE DATA POINTER 
CONTENTS OF BODY_AREA1. GO TO OF SUCCESSIVE COMPONENTS IN THE I-TH 
NULL_LIST. */ LIST WITHIN BODY_AREA1]L. */ 
ON AREA Cl = TEMP-—>OLINKS$ 
GO TO DO WHILE 
NULL_LIST3$ (C1-~=NULL) $ 
/* IF ALL OFFSET VALUES IN ALLCCATE COMPONENT2 IN(BODY_ AREA2) 
OHEAD_ARRAY ARE NULLO, GO TO SET(C2)3$ 
NULL LIST. */ SAVE->LINK, SAVE = C23 
DO I = LBOUND(OHEAD_ARRAY, 1) C2->DATA = C1->0DATA;3 
TO HBOUND(OHEAD_ARRAY,1)3 IF 
IF OHEAD_ARRAY(I) -~= NULLO C1->OLINK = NULLO 
THEN GO TO GO53 THEN 
END; , | Cl = NULLS 
GO TO NULL_LISTs ELSE 
GO5: Cl = C1—->SOLINKS 
/* IF HEAD_ARRAY IS SMALLER THAN END; 
OHEAD_ARRAY GO TO NULL_LIST. */ | 4* ASSIGN A NULL VALUE TO LINK IN 
IF LAST COMPONENT OF J-TH LIST IN 
DIM(HEAD_ARRAY,1)<DIM(QHEAD_ARRAY,1) BODY_AREA2. */ 
THEN SAVE->LINK = NULLS 
GO TO /* CONVERT NEXT LIST IN BODY_AREA1 
NULL_LIST3$ BY EXECUTING NEXT CYCLE OF CONVERT 


/* ASSOCIATE OFFSETS QHEAD_ARRAY AND 
OLINK WITH BODY_AREA2 AND OFFSET 
ODATA WITH DATA_AREA. */ 
DUMMY_POINTER1 = ADDOR(BODY_AREA2) $ 
DUMMY_POINTER2 = ADOR(DATA_AREA);$ 

/* CONVERT EACH RELOCATABLE POINTER 
LIST IN BODY_AREA1 TO AN ABSOLUTE 
POINTER LIST IN BODY_AREA2. */ 

J = LBOUND(HEAD_ARRAY,1)-135. 


BEGIN_CONVERT_LOOP: 


DO 


I = LBOUND(QHEAD_ARRAY,1) 

TO HBQUND (OHEAD_ARRAY,1)35 

J=zJ5+ 13 

/* IF I-TH OFFSET IN OQHEAD_ARRAY IS 
NULLO, SET J-TH POINTER IN 
HEAD_ARRAY TO NULL» AND CONVERT NEXT 


LOOP. */ 


END_CONVERT_LOOP: 


END; 


NULL_LIST: 


END 


/* THIS POINT IS REACHED WHEN ALL 
RELOCATABLE LISTS IN BODY_AREA1 

HAVE BEEN CONVERTED TO ABSOLUTE LISTS 
IN BODY_AREA2. THEREFORE, RETURN 


SUBROUTINE CONTROL TO POINT OF 


INVOCATION. ¥*/ 

RETURNS 

/* IF THIS POINT IS REACHED, 
ASSIGN A NULL VALUE TO EACH 
ELEMENT OF HEAD_ARRAY. */ 


HEAD_ARRAY = NULL3$ 
CON_PRAS$ 


Figure 2.7B. The CON_PRA subroutine used to convert relocatable pointer lists from relocatable to absolute form 
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CON_LRA Subroutine 


Figures 2.8A and 2.8B present the CON LRA subroutine, 
which converts relocatable lists of lists to absolute form. 
The subroutine uses six arguments: the body area and head 
array of the relocatable lists of lists being converted, the 
body area and head array that are to receive the absolute 
lists of lists during conversion, the data area, which is 


CON_LRA Subroutine 


Purpose 


To convert lists of lists from relocatable to absolute 
form 


Reference 


CON_LRA(BODY_AREA1, OHEAD_ARRAY, 
BODY_AREA2, HEAD_ARRAY, 
DATA_AREA,#SUBS) 


Entry-Name Declaration 


DECLARE CON_LRA 
ENTRY(AREA(*), (“)OFFSET 
(DUMMY_BODY_AREA), AREA(*), 
(*)POINTER, AREA(*),FIXED 
DECIMAL); 


Meaning of Arguments 


— the area that contains the 
bodies of the relocatable 
lists being converted to 
absolute form | 


BODY_AREA1 


OHEAD_ ARRAY — the array that contains the 
offset heads of the relocatable 
lists in BODY_AREAT1 


shared by both the relocatable and absolute forms of the 
lists of lists, and the number of sublists. 

The code in CON_ LRA indicates an optional use of the 
recursive function procedure CON shown in the Appendix. 
CON examines the type code in each list component and 
takes appropriate conversion action. CON returns a pointer 
value. 


BODY AREA2 — the area that receives the 
bodies of the lists after they 
have been converted to 
absolute form 


HEAD ARRAY ~ — the array that receives the 
pointer heads of the absolute 
lists in BODY _ AREA2 


DATA_AREA — the area that contains the 
data values of the lists before 
and after conversion 


#SUBS — the number of sublists 
Remarks 


BODY_AREA1, BODY_AREA2, and DATA_ AREA 
can have any storage class and be of arbitrary size. 

If BODY _AREA2 is not large enough to receive the 
converted components of BODY _AREAT1, or if 
HEAD_ARRAY is smaller than OHEAD_ ARRAY, 

or if all positions of OHEAD ARRAY contain null 
offset values, then HEAD ARRAY is filled with 

null pointer values, and the content of BODY AREA2 
becomes undefined. 


Other Programmer-Defined Procedures Required 
CON (optional) 

Method 
Each relocatable list in BODY AREA‘T1 is recon- 
structed, component by component, as an absolute 


list in BODY AREA2. After conversion, both types 
of lists share DATA_ AREA. 


Figure 2.8A. Description of the CON_LRA subroutine for converting lists of lists from relocatable to absolute form 
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CON_LRA: | : | 
PROCEDURE (BODY_AREA1,OHEAD_ARRAY sy 


DECLARE 


GO 


IF 


THEN 
GO 


NM NM PM &— NH N/M A mH M/W AP AY 


BODY_AREA2, HEAD_ARRAY» DATA_AREA, © 
#SUBS)3 | 


#SUBS FIXED DECIMAL, 
(SAVE, KEEP, PAC #SUBS)) POINTER» 


/* PARAMETER #SUBS IS NOT NECESSARY 
WHEN FUNCTION CON 


IS USED */ 
(BODY_AREA1 »BODY_AREA2 ,DATA_AREA) 
AREA(*), 

DUMMY_BODY_AREA 
BASED(DUMMY_BODY_POINTER) AREA, 
DUMMY_DATA_AREA | 
BASED(DUMMY_DATA_POINTER) AREA, 
HEAD_ARRAY(*) POINTER, 
(OUMMY_BODY_POINTER, 
DUMMY_DATA_POINTER»C1sC2) POINTERs 
OHEAD_ARRAY(#) 

OFFSET ( DUMMY_BODY_AREA), 

1 D_COMPONENT1 BASED(C1), 

D_OTYPE CHARACTER(1), 

D_OVALUE OFFSET(DUMMY_DATA_AREA) 
D_OLINK OFFSET(DUMMY_BODY_AREA), 
L_COMPONENT1] BASED(C1)> 
L_OTYPE CHARACTER(1), 

LLOVALUE OFFSET(DUMMY_BODY_AREA)» 
L_OLINK OFFSET(DUMMY_BODY_AREA), 
COMPONENT2 BASED(C2), 
TYPE CHARACTER(1), 

VALUE POINTER, 

LINK POINTER; 

/* IF AREA CONDITION OCCURS, 
BODY_AREA2 IS TOO SMALL TO RECEIVE | 
CONTENTS OF BODY_AREAL. GO TO 
NULL_LIST. */ | 

ON AREA 

TO 

NULL_LIST; 

/* IF HEAD_LARRAY IS SMALLER THAN 
OHEAD_ARRAY,» GO TO NULL_LIST. */ 


DIM(HEAD_ARRAY,1)<DIM(OHEAD_ARRAY 1) 
TO 


NULL_LIST$ 
/* ASSOCIATE OFFSETS OHEAD_ARRAY, 


OLOLINK, L_OVALUE ANO L_OLINK WITH 


BEGIN_CO 
D0 


BODY_AREAl, AND OFFSET D_OVALUE WITH 
DATA_AREA. */ 

DUMMY_BODY_POINTER = 
ADDR(BODY_AREAL)3 
DUMMY_DATA_POINTER = 
ADDR(DATA_AREA); | 

/* CONVERT EACH RELOCATABLE LIST OF 
LISTS IN BODY_AREAl TO AN ABSOLUTE 
LIST OF LISTS IN BODY_AREA2. */ 

PA = NULL3 

J = LBOUND(HEAD_ARRAY»1)-13 
NVERT_LOOP: 


= LBOUND(CHEAD_ARRAY, 1) 

O HBOUND(QHEAD_ARRAYs1)3 
J+ 13 

9 

IF OHEAD_ARRAY(I) = NULLO 

THEN DO; 

HEAD_ARRAY(J) = NULL; 

GO TO END_CONVERT_LCOP; 


I 
T 
J 
K 


“END; 


/* OPTIO 
/* TEST 


N */ 
*/ IF #SUBS -= 1 THEN GO TO NO_CON; 


USE_CON: 
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/* USE THE FOLLOWING CODE 

TO EMPLOY FUNCTION CON 

FOR CONVERSIONS */ 

HEAD_ARRAY(J) = CON(QHEAD_ARRAY(I), 
BODY_AREA1, BODY_AREA2, DATA_AREA)$ 


60 TO END_CONVERT_LOOP; 


/* END OF OPTION */ 


NO_CON: 


Cl = QHEAD_ARRAY(1)3 
ALLOCATE COMPONENT2 IN(BODY_AREA2) 
SET(C2)35 
SAVE, KEEP, HEAD_ARRAY(J) = C23 
C2- >TYPE = *L'; 
PA(K) = Cl -—> L_OVALUE; 
IF Cl- ->L_OLINK = NULLO 
THEN Cl = NULLS 
ELSE Cl = C1->L_OLINKS 
DO WHILE(C1 -~= NULL); 
K = K + 135 
ALLOCATE COMPONENT2 IN(BODY_AREA2) 
SET(C2)3$ 
SAVE-SLINK = C235 
SAVE = C23 
C2->TYPE = *L*;5 
PA(K) = Cl => L_OVALUES 
IF C1-SL_LOLINK = NULLO 


THEN Cl = NULL3 
ELSE Cl = C1->L_OLINKS 
END; 


SAVE->LINK = NULL$ 


D_LISTs 


DO L = 1 TO #SUBS; 


Cl = PA(L)s | | 

IF Cl=NULL THEN GOTO ENOD_O_LIST; 
ALLOCATE COMPONENT2 IN(BODY_AREA2) 
SET(C2)3 

SAVE = C23 

C2->TYPE = "D*; 

KEEP->VALUE = C23 

KEEP = KEEP=>LINK$ 

IF C1->D_OVALUE = NULLO. 


THEN C2->VALUE = NULL3 
ELSE C2->VALUE = C1->D_OVALUE; 
IF Cl->D_OLINK = NULLO | 


THEN Cl = NULLS 

ELSE Cl = Cl- >0_ OLINKS 

DO WHILE (Cl -~= NULL)3$ 

ALLOCATE COMPONENT2 IN(BODY_ AREA2) 
SET(C2)35 

SAVE=>LINK = C235 

SAVE = C235 

C2->TYPE = "D*$ . 

IF Cl->D_OVALUE = NULLO 


THEN C2->VALUE = NULLS 
ELSE C2->VALUE = C1->0 _OVALUE; 
IF C1l->D_OLINK = NULLO 


THEN Cl = NULLS | 

ELSE Cl = C1->D_OLINKS 
ENO; | 
SAVE->LINK = NULLS$ 


-END_D_LIST: END; 
END_CONVERT_LOOP: 


END$ 


/* WHEN THIS POINT IS REACHED, ALL 
RELOCATABLE LISTS OF LISTS IN 
BODY_AREA1 HAVE BEEN CONVERTED TO 
ABSOLUTE LISTS OF LISTS IN 
BODY_AREA2. THEREFORE», RETURN 


- SUBROUTINE CONTROL TO POINT OF 


INVOCATION. */ 

RETURNS 

4* IF THIS. POINT IS REACHED, 
ASSIGN A NULL VALUE TO EACH 
ELEMENT OF HEAD_ARRAY. */ 


NULL_LIST: 
HEAD_ARRAY = NULL3$ 
END 

CON_LRAS 


Figure 2.8B. The CON_LRA subroutine used to convert 
relocatable lists of lists from relocatable to 
absolute form 


MOVING RELOCATABLE LISTS 


The following discussions develop two subroutines for 
moving relocatable lists from one storage area to another: 


1. MOVE_RDL, which moves relocatable data lists 

2. MOVE_RPL, which moves either relocatable pointer 
lists or relocatable lists of lists. This subroutine can be 
used with either type of list because both types have 
a head, a body area, and a data area. 


MOVE_RDL Subroutine 
Purpose 
To move relocatable data lists 


Reference 


MOVE_RDL(BODY_AREA1, OHEAD_ARRAY1, 
BODY_AREA2, OHEAD_ARRAY2) 


Entry-Name Declaration 


DECLARE MOVE_RDL 
ENTRY(AREA(*), (*)OFFSET 
(DUMMY_BODY_AREA1), AREA(*), 
(")OFFSET(DUMMY_BODY_AREA2)); 


Meaning of Arguments 


BODY _AREA1 — the area that contains the 
relocatable lists being moved 


OHEAD_ ARRAY1 — the array that contains the 
offset heads of the relocatable 
lists in BODY _AREA1 


MOVE _RDL Subroutine 


Figures 2.9A and 2.9B present the MOVE_RDL sub- 
routine, which moves relocatable data lists from one area to 
another. The subroutine uses four arguments: the body area 
and head array of the source lists, and the body area and 
head array that are to receive the relocatable lists when 
they are moved. 


BODY AREA2 — the area to which the reloca- 
table lists are moved 


OHEAD_ARRAY2 — the array that receives the 
offset heads of the relocatable 
lists in BODY _ AREA2 


Remarks 


BODY _AREA1 and BODY _AREA2 can have any 
storage class and be of arbitrary and unequal size. 

If BODY AREA2 is not large enough to receive 

the contents of BODY_AREAT1, or if OHEAD _ 
ARRAY 2 is smaller than OHEAD_ARRAY‘1, then. 
OHEAD_ARRAY 2 is set to NULLO, and the content 
of BODY _AREA2 becomes undefined. 


Other Programmer Defined Procedures Required 
None 

Method 
Assignment statements are used to move BODY _ 


AREA1 to BODY_AREA2 and OHEAD_ARRAY1 
to OHEAD_ARRAY2. 


Figure 2.9A. Description of the MOVE_RDL subroutine for moving relocatable data lists 
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MOVE_RDL:= 


PROCEDURE | 
(BODY_AREA1, CHEAOD_ARRAY1, 
BODY_AREA2, OHEAD_ARRAY2)35 


DECLARE 


(DUMMY_POINTER1, DUMMY_POINTER 2) 
POINTER, | 

(BODY_AREA1 »BODY_AREA2) AREA(*) , 
DUMMY_BODY_AREA1 BASED 
(DUMMY_POINTER1) AREA, 
DUMMY_BODY_AREA2 BASED 
(DUMMY_POINTER2) AREA; 
OHEAD_ARRAY1(*) OFFSET 
(DUMMY_BODY_AREA1), 
OHEAD_ARRAY2(*) OFFSET 
(DUMMY_BODY_AREA2) 3 i 

/* IF AREA CONDITION OCCURS | 
BODY_AREA2 IS TCO SMALL TO RECEIVE 
CONTENTS OF BODY_AREA1. SET 
OHEAD_ARRAY2 TO NULLO, AND GO TO END 
OF SUBROUTINE.*/ 

ON AREA 


BEGINS 


OHEAD_ARRAY2 = NULLO3 
GO TO 
END_MOVE_RDL; 


END; , 

/* ASSOCIATE QHEAD_ARRAY1 AND 
OHEAD_ARRAY2 WITH BODY_AREA1 ANC 
BODY_AREA2.*/ 

DUMMY_POINTER1 = ADDR(BODY_AREA1); 
DUMMY_POINTER2 = ADDR(BODY_AREA2); 
/* IF QHEAD_ARRAY2 IS SMALLER THAN 
OHEAD_ARRAY1, THEN SET OQHEAD_ARRAY2 
TO NULLO, AND GO TO END OF 
SUBROUTINE, OTHERWISE,» ASSIGN 
OHEAD_ARRAY1 TO OQHEAD_ARRAY2.*/ 


IF 
DIM(QHEAD_ARRAY2,1)<DIM(QHEAD_ARRAY1 51) 

THEN DO$ 

7 OHEAD_ARRAY2 = NULLO; 

GO TO 
END_MOVE_RDL3; 
END; 
ELSE 


OHEAD_ARRAY2 = QHEAD_ARRAY1; 
/4* ASSIGN BODY_AREA1 TO BODY_AREA2. 
AREA CONDITION MAY OCCUR.*/ 
BODY_AREA2 = BOOY_AREAILS$ 
END_MOVE_ROL: 
END 
MOVE_RDOL; 


Figure 2.9B. The MOVE_RDL subroutine used to move relocatable data lists from one area to another 
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MOVE _RPL Subroutine 


Figures 2.10A and 2.10B present the MOVE RPL sub- 
routine, which moves relocatable pointer lists and relocat- 
able lists of lists to new storage locations. The subroutine 
uses six arguments: the body area, head array, and data area 
of the source lists, and the body area, head array, and data 
area that are to receive the relocatable lists when they are 
moved. 


MOVE _RPL Subroutine 
Purpose 
To move relocatable pointer lists and lists of lists 


Reference 


MOVE_RPL(BODY_AREA1, OHEAD_ARRAY1, 
DATA_AREA1, BODY_AREA2, 
OHEAD_ARRAY2, DATA_AREA2) 


Entry-Name Declaration 


DECLARE MOVE_RPL 
ENTRY(AREA(*), (*)OFFSET 
(DUMMY_BODY_AREA\1), 
AREA(*), AREA(*), 
(*)OFFSET(DUMMY_BODY_AREA2), 
AREA(*)); 


Meaning of Arguments 


— the area that contains the 
bodies of the relocatable 
lists being moved 


BODY AREA1 


OHEAD_ARRAY1 — the array that contains the 
offset heads of the relocatable 
lists in BODY_AREA1 


— the area that contains the 
data values of the lists in 
BODY _AREAI1 


DATA_AREA1 


BODY _ AREA2 — the area that receives the 
contents of BODY _AREA1 


OHEAD_ARRAY2 — the array that receives the 
offset heads of the relocatable 


lists in BODY_AREA2 


DATA_AREA2 — the area that receives the data 


values of the lists in BODY _ 
AREA2 
Remarks 


BODY _AREA1, BODY_AREA2, DATA_AREA1, 
and DATA_AREA2 can have any storage class and 
be of arbitrary size. If BODY_AREA2 is not large 
enough to receive the contents of BODY _AREA1, 

or if DATA_AREA2 is not large enough to receive 
the contents of DATA_AREA1, or if OHEAD _ 
ARRAY 2 is smaller than OHEAD_ARRAY‘1, then 
OHEAD_ARRAY2 is set to NULLO, and the content 
of BODY_AREA2 and DATA_AREA2 becomes 
undefined. 


Other Programmer-Defined Procedures Required 
None 

Method 
Assignment statements are used to move BODY _ 
AREA1 to BODY_AREA2, OHEAD_ARRAY‘1 to 


OHEAD_ARRAY2, and DATA_AREA1 to 
DATA_AREA2. 


Figure 2.10A. Description of the MOVE RPL subroutine for moving relocatable pointer lists and lists of lists 
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MOVE_RPL: 3 

PROCEDURE (BCDY_AREA1,QHEAD_ARRAY1]»> | 
DATA_AREA1, BODY_AREA2, OHEAD_ARRAY2, 
DATA_AREA2)$ | 

DECLARE | . 
(BOOY_AREA1 ,DATA_AREA1 »BODY_AREA2, 
DATA_AREA2) AREA(¥) 9 | 
DUMMY_BODY_AREA1 
BASEO(DUMMY_POINTER1) AREA, 
DUMMY_BODY_AREA2 
BASED(DUMMY_POINTER2) AREA, 
OHEAD_ARRAY1(*) 
OFFSET(OUMMY_BODY_AREA1), 
OHEAD_ARRAY2(*) | 
OFFSET (OUMMY_ BODY_AREA2)3$ 
/* ITF AREA CONDITION OCCURS, 
BODY_AREA2 OR DATA_AREA2 IS TOO 
SMALL TO RECEIVE CONTENTS OF 
BODY_AREA1 OR DATA_AREA1. SET 
OHEAD_ARRAY2 TO NULLO,», AND GO TC END 
OF SUBROUTINE. */ 
ON AREA 

BEGIN; 
OHEAD_ARRAY2 = NULLOS3 

GO TO 

ENO_MOVE_RPLs$ 

ENO; 

/* ASSOCIATE QHEAD_ARRAY1 AND 


OHEAD_ARRAY2 WITH BOOY_AREA1 AND 
BODY_AREA2. */ 3 
DUMMY_POINTERIL ADDR(BODY_AREA1)$ 
DUMMY_POINTER2 ADOR(BODY_AREA2) $ 
/* IF QHEAD_ARRAY2 IS SMALLER THAN 
OHEAD_ARRAY1,» THEN SET OHEAD_ARRAY2 
TO NULLO, AND GO TO END OF 
SUBROUTINE. OTHERWISE ASSIGN 
OHEAD_ARRAY1 TQ QHEAD_ARRAY2. */ 


IF 
DIM(OHEAD_ARRAY2,1)< 
DIM(QHEAD_ARRAY1,1) 

THEN 
00; 


OHEAD_ARRAY2 = NULLO; 
GO TC 
| END_MOVE_RPL3 
END; 
ELSE 
| OHEAD_ARRAY2 = CHEAD_ARRAY1;3 . 
/* ASSIGN BODY_AREA1 TC BODY_AREA2 
AND DATA_AREA1] TO DATA_AREA2. AREA 
CONDITION MAY OCCUR. */ 
BODY_AREA2 = BODY_AREAL; 
DATA_AREA2 = DATA_AREAI;3 
END_MOVE_RPL? 
END 
MOVE_RPL; 


Figure 2.10B. The MOVE_ RPL subroutine used to move relocatable pointer lists and relocatable lists of lists to new storage locations 
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WRITING RELOCATABLE LISTS 


The following discussions develop two subroutines for 
writing relocatable lists into a file: 


1. WRITE _RDL, which writes relocatable data lists 

2. WRITE _RPL, which writes either relocatable pointer 
lists or relocatable lists of lists. This subroutine can be 
used with either type of list because both types have 
a head, a body area, and a data area. 


WRITE_RDL Subroutine 
Purpose 
To write relocatable data lists into a file 


Reference 


WRITE_RDL(DFILE, OHEAD_ARRAY, 
BODY_AREA, BODY_SIZE) 


~ Entry-Name Declaration 


DECLARE WRITE_RDL 
ENTRY(FILE RECORD OUTPUT, 
(*)OFFSET(DUMMY_BODY1), 
AREA(*), FIXED DECIMAL (5)); 


Meaning of Arguments 


DFILE — the file into which the 
relocatable lists are written 


OHEAD_ ARRAY -— the array that contains the 
offset heads of the relocatable 
lists 


BODY AREA — the area that contains the 
bodies of the relocatable 
lists 


BODY_SIZE — the size of BODY_AREA in 
bytes 


WRITE_RDL Subroutine 


Figures 2.11A and 2.11B present the WRITE RDL sub- 
routine, which writes relocatable data lists into a file. The 
subroutine uses four arguments: the file that receives the 
lists, the head array and body area of the relocatable lists, 
and the size of the body area in bytes. The head array and 
body area are written as separate self-defining records in 
that order. 


Remarks 


DFILE must be a sequentially buffered output file. 
OHEAD_ARRAY and BODY_AREA can be of any 
storage class and have arbitrary size, and are written 
as separate logical records in that order. The records 
are self-defining: OHEAD ARRAY is preceded by 
a count of its elements, and BODY_ AREA is 
preceded by its storage size (BODY _SIZE), which 
does not include the control storage internally 
associated with an area. 


Other Programmer-Defined Procedures Required 


None 


‘Method 


Separate LOCATE statements are executed for each 
of the following record descriptions: 


1 OHEAD_ RECORD BASED(OUTPOINTER1), 
2 OUT_OHEAD_ SIZE FIXED BINARY (16,0), 
2 OUT_OHEAD_ARRAY 
(BINARY_OHEAD_ SIZE 
REFER(OUT_OHEAD_SIZE))OFFSET 
(DUMMY_BODY2), 
1 BODY_RECORD BASED(OUTPOINTER2), 
2 PADDING2 CHARACTER (4), 
2 OUT_BODY_SIZE FIXED BINARY (16,0), 
2 OUT_BODY_AREA AREA 
(BINARY_BODY_ SIZE 
REFER(OUT_BODY_SIZE)), 


Figure 2.11A. Description of the WRITE_RDL subroutine for writing relocatable data lists into a file 
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WRITE_RDL? 


‘DECLARE 


END 


PROCEDURE(OUTFILE» OHEAD_ Aeens 
BODY_ AREA, BODY_ SIZE)$ | 


(DUMMY_POINTER1, DUMMY_POINTER2, 
QOUTPOINTER1, QUTPOINTER2) | 
POINTER, | 

DUMMY_BODY1 AREA 
BASED(DUMMY_POINTER1) + 

DUMMY_BODY2 AREA 
BASED(DUMMY_POINTER2), 
OHEAD_ARRAY(*#) 

OFFSET (DUMMY_BODY1); 

BODY_AREA AREA (*), 

BODY_SIZE FIXED DECIMAL(5), 
BINARY_OHEAD_SIZE FIXED BINARY(16%0), 
BINARY_BODY_SIZE FIXED BINARY( 16.0), 
OUTFILE FILE RECORD OUTPUT, 

1 OHEAD_RECORD BASED(QUTPOINTERL)» 
2 QUT_OHEAD_SIZE FIXED BINARY( 16,0), 
2 QUT_OHEAD_ARRAY (BINARY_OHEAD_SIZE 
REFER(OUT_OHEAD_SIZE)) 
OFFSET(DUMMY_BODY2), 

1 BCOY_RECORD BASED(QUTPOINTER2)s 

2 PADDING2 CHARACTER(4), 

2 OUT_BODY_SIZE FIXED BINARY(16,0)5 
2 OUT_BODY_AREA AREA 
(BINARY_BODY_SIZE 
REFER(OUT_BODY_SIZE))3 

/* ASSOCIATE OHEAD_ARRAY AND 
QUT_OHEAD_ARRAY WITH BODY_AREA. */ 
DUMMY_POINTER1L,»DUMMY_POINTER2 = 
ADDR(BODY_AREA) ; 

/* INITIALIZE SIZE OF 
QUT_OHEAD_ARRAY */ 
BINARY_OHEAD_SIZE = 
DIM(OHEAD_ARRAY, 1); 

/* INITIALIZE SIZE OF 

OUT_BODY_AREA */ 

BINARY_BODY_SIZE = BODY_SIZE;3 

/* LOCATE STORAGE. IN OUTPUT BUFFER 
FOR OHEAD_RECORD, AND ASSIGN ACORESS 
OF LOCATION TO OUTPOINTER1. */ 
LOCATE QHEAD_RECORD FILE(OUTFILE) 
SET(QUTPOINTERL)3 

/* ASSIGN OHEAD_ARRAY TO 
QUT_OHEAD_ARRAY IN QHEAD_RECORD. */ 
GOUT POINTER1->OUT_OHEAD_ARRAY = 
OHEAD_ARRAY; 

/* LOCATE STORAGE IN OUTPUT BUFFER 
FOR BODY_RECORD, AND ASSIGN ADORESS 
OF LOCATION TO OUTPOINTER2. */ 
LOCATE BODY_RECORD FILE(OUTFILE) 
SET (OUTPOINTER2)3 

/* ASSIGN BODY_AREA TO QUT_BODY_AREA 
IN BODY_RECORD. */ ie 
OUTPOINTER2->OUT_BODY_AREA = 
BODY_AREA; 


WRITE ROLS 


Figure 2.11B. The WRITE_ RDL subroutine used to write 
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relocatable data lists into a file 


WRITE_RPL Subroutine 


Figures 2.12A and 2.12B present the WRITE RPL sub- 
routine, which writes relocatable pointer lists and relocat- 
able lists of lists into a file. The subroutine uses six 
arguments: the file that receives the relocatable lists, the 
head array of the lists, the containing body area and its size, 
and the associated data area and its size. The head array, 
the body area, and the data area are written as separate 
self-defining records in that order. | 


WRITE_RPL Subroutine 
Purpose 


To write relocatable pointer lists and lists of lists into 
a file 


Reference 


WRITE_RPL(LFILE, OHEAD_ARRAY, 
BODY _AREA, BODY_ SIZE, 
DATA_AREA, DATA_SIZE) 


Entry-Name Declaration 


DECLARE WRITE_ RPL 
ENTRY(FILE RECORD OUTPUT, (*)OFFSET 
(DUMMY_ BODY1), AREA(*), FIXED 
DECIMAL (5), AREA(*), FIXED 
DECIMAL (5)); 


Meaning of Arguments 


LFILE — the file into which the relo- 
catable lists are written 


OHEAD_ ARRAY — the array that contains the 
| offset heads of the relocatable 
lists 


BODY AREA — the area that contains the 
bodies of the relocatable 
lists 

BODY _SIZE — thesizeof BODY AREA in 
bytes 

DATA_AREA — the area that contains the data 


values of the relocatable lists 


DATA_SIZE — the sizeof DATA_AREA in 
bytes 


Remarks 


LFILE must be a sequentially buffered output file. 
OHEAD_ARRAY, BODY_ AREA, and DATA _ 
AREA can be of any storage class and have arbitrary 
size, and are written as separate logical records in 
that order. The records are self-defining: OHEAD _ 
ARRAY is preceded by a count of its elements, and 
BODY_AREA and DATA_ AREA are preceded by 
their storage sizes, which do not include the control 
storage internally associated with the areas. 


Other Programmer-Defined Procedures Required 


None 


Method 


Separate LOCATE statements are executed for each 
of the following record descriptions: 


1 OHEAD_RECORD BASED(OUTPOINTER), 
2 OUT_OHEAD_ SIZE FIXED BINARY (16,0), 
2 OUT_OHEAD_ ARRAY 
(BINARY_OHEAD_ SIZE 
REFER(OUT_OHEAD_ SIZE)) OFFSET 
(DUMMY_BODY2), 
1 BODY_RECORD BASED(OUTPOINTER), 
2 PADDING2 CHARACTER(4), 
2 OUT_BODY_ SIZE FIXED BINARY (16,0), 
2 OUT_BODY_AREA AREA 
(BINARY_BODY_ SIZE 
REFER(OUT_BODY_SIZE)), 
1 DATA_RECORD BASED(OUTPOINTER), 
2 PADDING3 CHARACTER(4), 
2 OUT_DATA_SIZE FIXED BINARY (16,0), 
2 OUT_DATA_AREA AREA 
(BINARY_DATA_SIZE 
REFER(OUT_DATA_SIZE)), 


Figure 2.12A. Description of the WRITE_RPL subroutine for writing relocatable pointer lists and lists of lists into a file 
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WRITE_RPL: 


DECLARE 


PROCEDURE (OUTFILE »OHEAD_ARRAY, 
BODY_AREA,BODY_SIZE,DATA_AREA, 
DATA_SIZE)$ 


(DUMMY_POINTER1, ODUMMY_POINTER2, 
OUTPOINTER) POINTER, 

DUMMY_BOCDY1 AREA 
BASED(DUMMY_POINTERIL) >» 

DUMMY_BODY2 AREA | 

BASED (DUMMY_POINTER2) >» 
OHEAD_ARRAY(*) OFFSET(DUMMY_BODY1) » 
BODY_AREA AREA (¥*)5 

BOOY_SIZE FIXED DECIMAL(5), 
DATA_AREA AREA (¥*), 


“DATA_SIZE FIXED DECIMAL(5), 


OUTFILE FILE RECORD OUTPUT, 
BINARY_OHEAD_SIZE FIXED BINARY (16,0); 


' BINARY_BODY_SIZE FIXED BINARY( 1690), 


BINARY_DATA_SIZE FIXED BINARY( 1650), 
1 OHEAD_RECORD BASED(OUTPOINTER),» 

2 OUT._OHEAD_SIZE FIXED BINARY(1650), 
2 OUT_OHEAD_ARRAY(BINARY_OHEAD_SIZE 
REFER(OUT_OHEAD_SIZE)) 
OFFSET(DUMMY_BODY2)>, 

1 BODY_RECORD BASED(OUTPOINTER)» 

2 PADDING2 CHARACTER(4)> 

2 OUT_BODY_SIZE FIXED BINARY(16s0)» 
2 OUT_BODY_AREA AREA 
(BINARY_BODY_SIZE REFER 
(QUT_BODY_SIZE)), 

1 DATA_RECORD BASED(OUTPOINTER )» 

2 PADDING CHARACTER(4)> 

2 OUT_DATA_SIZE FIXED BINARY(16,0), 
2 QUT_DATA_AREA AREA 
(BINARY_DATA_SIZE 


ENO 


REFER(OQUT_DATA_SIZE))3 

/* ASSOCIATE OHEAD_ARRAY AND | 
OUT_OHEAD_ARRAY WITH BODY_AREA. */ 
DUMMY_POINTER1,DUMMY_POINTER2 = 
ADOR(BODY_AREA)3 | 
/* INITIALIZE SIZE OF HEAD ARRAY IN 
OHEAD_RECORD, SIZE OF BODY AREA IN 
BODY_RECORD, AND SIZE OF DATA 

AREA IN DATA_RECORD. */ 
BINARY_OHEAD_SIZE = 
DIM(QHEAD_ARRAY»1)3 
BINARY_BODY_SIZE = BOOY_SIZE;3 
BINARY_DATA_SIZE = DATA_SIZE3 

/* LOCATE STORAGE IN OUTPUT BUFFER 
FOR OHEAD_RECORD, AND ASSIGN 
OHEAD_ARRAY TO QUT_OHEAD_ARRAY. */ 


LOCATE OQHEAD_RECORD FILE(OUTFILE) 


SET (OUTPOINTER) 3 

OUT POINTER->OUT_OHEAD_ARRAY = 
GHEAD_ARRAY3 Zz 

/* LOCATE STORAGE IN OUTPUT BUFFER 
FOR BODY_RECORD, ANO ASSIGN 
BODY_AREA TO OUT_BODY_AREA. */ 
LOCATE BODY_RECORD FILE(OUTFILE) 
SET(CUTPOINTER)$ 
OUTPOINTER->CGUT_BODY_AREA = 
BODY_AREA; 

/* LOCATE STORAGE IN OUTPUT BUFFER 
FOR DATA_RECORD, AND ASSIGN DATA 
AREA TO OQUT_DATA_AREA. */ 

LOCATE DATA_RECORD FILE(OUTFILE) 
SET (QUTPOINTER); 
OUTPOINTER->OUT_DATA_AREA = 
DATA_AREA; 


WRITE_RPLS3 


Figure 2.12B. The WRITE_RPL subroutine used to write relocatable pointer lists and relocatable lists of lists into a file 
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READING RELOCATABLE LISTS 


The following discussions develop two subroutines for 
reading relocatable lists from a file: | 


1. READ_RDL, which reads relocatable data lists 

2. READ_RPL, which reads either relocatable pointer 
lists or relocatable lists of lists. This subroutine can be 
used with either type of list because both types have 
a head, a body area, and a data area. 


READ_RDL Subroutine 
Purpose 


To read relocatable data lists from a file 


Reference 


READ_RDL(DFILE, OHEAD_ ARRAY, 
BODY_AREA, BODY_ SIZE) 


Entry-Name Declaration 


DECLARE READ_RDL 
ENTRY(FILE RECORD INPUT, (*)OFFSET 
(DUMMY_BODY1),AREA(*), FIXED 
DECIMAL (5)): 


Meaning of Arguments 


DFILE — the file from which the 
| relocatable data lists are read 


OH EAD AR RAY — the array that receives the 
offset heads of the relocatable 
lists 


BODY _AREA — the area that receives the 
bodies of the relocatable lists 


BODY _ SIZE — the size of BODY_AREA in 
: bytes 


READ_RDL Subroutine 


Figures 2.13A and 2.13B present the READ_RDL sub- 
routine, which reads relocatable data lists from a file. The 
subroutine uses four arguments: the file that contains the 
relocatable lists, the head array and body area that are to 
receive the lists, and a variable that receives the size of the 
body area. The head array and body area are assumed to be 
contained in separate self-defining records, which are read 
in-that order. 


Remarks 


DFILE must be a sequentially buffered input file. 
OHEAD_ARRAY and BODY _AREA can be of any 
storage class and have arbitrary size; their values are 
read as separate logical records in that order. The 
records are self-defining: the record for OHEAD _ 
ARRAY is preceded by a count of its offset values, 
and the record for BODY _ AREA is preceded by the 
size of the area in bytes. The sizeof BODY_AREA 
is assigned to BODY_SIZE. An attempt to read past 
the end of DFILE assigns a zero value to BODY_ SIZE 
and returns control to the invoking procedure. 


Other Programmer-Defined Procedures Required 
None 
Method 


Separate READ statements are executed for each of 
the following record descriptions: 


1 OHEAD_RECORD BASED(INPOINTER), 
2 IN_OHEAD_ SIZE FIXED BINARY (16,0), 
2 IN_OHEAD_ARRAY 
(BINARY_OHEAD_ SIZE 
REFER(IN_OHEAD_SIZE)) 
OFFSET(DUMMY_BODY2), 
1 BODY_RECORD BASED(INPOINTER), 
2 PADDING2 CHARACTER (4), 
2 IN_BODY_SIZE FIXED BINARY(16,0), 
2 IN_BODY_AREA AREA 
(BINARY_BODY_SIZE 
REFER(IN_BODY_SIZE)), 


Figure 2.13A. Description of the READ_RDL subroutine for reading relocatable data lists from a file 
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READ_RDL: | } | 
PROCEDURE(INFILE, OHEAD_ARRAY, 
BODY_AREA,BODY_SIZE)5 
DECLARE 
(OUMMY_POINTER1, DUMMY_POINTER2, 
INPOINTER) POINTER, 
DUMMY_BODY1 AREA 
BASED(DUMMY_POINTER1), 
DUMMY_BODY2 AREA 
BASED(DUMMY_POINTER2), 
OHEAD_ARRAY(*) OFFSET(DUMMY_BODY1), 
BODY_SIZE FIXED DECIMAL(5), 
BODY_AREA AREA (*)> 
INFILE FILE RECORD INPUT, 
BINARY_OHEAD_SIZE FIXED BINARY (16,0)> 
BINARY_BODY_SIZE FIXED BINARY(1650)>+ 
1 OHEAD_RECORD BASED(CINPOINTER) » 
2 IN_OHEAD_SIZE FIXED BINARY(1630);, 
2 IN_OHEAD_ ARRAY (BINARY_OHEAD_SIZE 
~REFERCIN_OHEAD_SIZE)) 
OFFSET(OUMMY_BODY2), 
1 BCOY_RECORD BASEDCINPOINTER) » 
2 PADDING2 CHARACTER(4), 
2 IN_BODY_SIZE FIXED BINARY(16,0), 
2 IN_BODY_AREA AREA 
(BINARY_BODY_SIZE 
REFERCIN_BODY_SIZE))5 


/* AT END OF INFILE, SET BODY_SIZE TO: 


ZERG, AND ENC SUBROUTINE. */ 
ON ENDFILECINFILE) 

BEGINS 
BOOY_SIZE = 03 

GO TO | 

END_READ_RDL S$ 

ENO; 
/* ASSOCIATE QHEAD_ARRAY ANO 
IN_QHEAD_ARRAY WITH BODY_AREA. */ 
DUMMY_POINTER1,D0UMMY_POINTER2 = 
ADDR(BODY_AREA)$ 
/* READ NEXT LOGICAL QHEAD_RECORD 
FROM INFILE, AND SET INPOINTER TO 
LOCATION OF OHEAD_RECORD IN INPUT 
BUFFER. */ 
READ FILECINFILE) SETCINPOINTER); 
/* ASSIGN IN_OHEAD_ARRAY WITHIN 
OHEAD_RECORD TCO OHEAD_ARRAY. */ 
OHEAD_ARRAY = 
INPOINTER->IN_OHEAD_ARRAY S$ 
/* READ NEXT LOGICAL BODY_RECORD 
FROM INFILE, AND SET INPOINTER TO 
LOCATION OF BODY_RECORD IN INPUT 
BUFFER. */ 
READ FILECINFILE) SETCINPOINTER)S 
/* ASSIGN IN_BODY_AREA WITHIN 
BODY_RECORD TO BODY_AREA. */ 
BODY_AREA = 

a INPOINTER->IN_BODY_AREAS 

ENO_READ_ROL: 

END 
READ_RDL$ 


Figure 2.13B. The READ_RDL subroutine used to read 
relocatable data lists from a file 
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READ _RPL Subroutine 


"Figures 2.14A and 2.14B present the READ RPL sub- 


routine, which reads relocatable pointer lists and relocat- 
able lists of lists from a file. The subroutine uses six 


_ arguments: the file that contains the relocatable lists, an 


array to receive the heads of the lists, an area and a variable 
to receive the body and the body size of the lists, and an 
area and a variable to receive the data area and the data-area 
size of the lists. The head array, the body area, and the data 
area are assumed to be contained in separate self-defining 


records, which are read in that order. 


READ_RPL Subroutine 
Purpose 


To read relocatable pointer lists and lists of lists from 
a file 


Reference 


READ_RPL(LFILE, OHEAD_ARRAY, 
BODY_AREA, BODY_SIZE, 
DATA_AREA, DATA_SIZE) 


Entry-Name Declaration 


DECLARE READ_RPL 
ENTRY (FILE RECORD INPUT, (*)OFFSET 
(DUMMY_BODY1), AREA(*), FIXED 
DECIMAL(5), AREA(*), FIXED 
DECIMAL (5)); 


Meaning of Arguments 


LFILE — the file from which the 
relocatable lists are read 


OHEAD_ ARRAY -— the array that receives the 
offset heads of the relocatable 
lists 


BODY AREA — the area that receives the 
bodies of the relocatable lists 


BODY_SIZE — the size of BODY_AREA in 
bytes 
DATA_AREA — the area that receives the 


data values of the relocatable 
lists — 


DATA_ SIZE — the size of DATA_AREA in 
bytes 


Remarks 


LFILE must be a sequentially buffered input file. 
OHEAD_ARRAY, BODY_AREA, and DATA_AREA 
can be of any storage class and have arbitrary size; 
their values are read as separate logical records in 
that order. The records are self-defining: the record 
for OHEAD_ARRAY is preceded by a count of its 

_ offset values, and the records for BODY _AREA and 
DATA_AREA are preceded by their storage sizes. 
The size of BODY_AREA is assigned to BODY _ 
SIZE, and DATA_SIZE receives the size of DATA __ 
AREA. An attempt to read past the end of LFILE 
assigns zero values to BODY_ SIZE and DATA_ SIZE 
and returns control to the invoking procedure. 


Other Programmer-Defined Procedures Required 
None 
Method 


Separate READ statements are executed for each of 
the following record descriptions: 


1 OHEAD_ RECORD BASED(INPOINTER), 
2 IN_OHEAD_ SIZE FIXED BINARY (16,0), 
2 1IN_OHEAD_ ARRAY 
(BINARY_OHEAD_ SIZE 
REFER(IN_OHEAD_SIZE)) OFFSET 
(DUMMY_BODY2), 
1 BODY_RECORD BASED(INPOINTER), 
2 PADDING2 CHARACTER(4), 
2 IN_BODY_ SIZE FIXED BINARY(16,0), 
2 IN_BODY_AREA AREA 
(BINARY_BODY_ SIZE 
REFER(IN_BODY_SIZE)), 
1 DATA_RECORD BASED(INPOINTER), 
2 PADDING3 CHARACTER(4), 
2 IN_DATA_SIZE FIXED BINARY(16,0), 
2 IN_DATA_AREA AREA 
(BINARY_DATA_ SIZE 
REFER(IN_DATA_SIZE)), 


Figure 2.14A. Description of the READ_RPL subroutine for reading relocatable pointer lists and lists of lists from a file. 
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 READ_RPL: 


PROCEDURE(INFILE,OHEAD_ARRAY, 
BODY_AREA, BODY_SIZE,DATA_AREA, 
DATA_SIZE)$ 


DECLARE 


(DUMMY_POINTER1, DUMMY_POINTER2, 
INPOINTER) “POINTER, 
DUMMY_BODY1 AREA 
BASED(DUMMY_POINTERL) » 
DUMMY_BODY2 AREA 
BASED (DUMMY_POINTER2) > 
OHEAD_ARRAY(*) 
OFFSET(DUMMY_BODY1), 
BODY_AREA AREA (*), 
BODY_SIZE FIXED DECIMAL(5), 
DATA_AREA AREA (*), 
DATA_SIZE FIXED DECIMAL(5), 
INFILE FILE RECORD INPUT, 


BINARY_OQHEAD_SIZE FIXED BINARY(16,0), 
BINARY_BODY_SIZE FIXED BINARY(1690), . 
BINARY_DATA_SIZE FIXED BINARY( 16,0), 


1 QHEAD_RECORD BASEDCINPOINTER ), 


2 IN_OHEAD_SIZE FIXED BINARY(16,0), 


2 IN_OHEAD_ARRAY(BINARY_OHEAD_SIZE 
REFER(CIN_OHEAD_SIZE)) 
OFFSET(DUMMY_BODY2), 

1 BOOY_RECORD BASEDCINPOINTER) » 

2 PADDING2 CHARACTER(4), 


2 IN_BODY_SIZE FIXED BINARY(1690),. 
2 IN_BODY_AREA AREA(BINARY_BODY_ prec 


REFER(IN_BODY_SIZE)), 

1 DATA_RECORD BASED(INPOINTER), 

2 PADDING3 CHARACTER(4), | 

2 IN_DATA_SIZE FIXED BINARY(16,0), 


2 IN_DATA_AREA AREA(BINARY_DATA_SIZE 


REFER(IN_DATA_SIZE))3$ 


/* AT END OF INFILE, SET BODY_SIZE 
AND DATA_SIZE TO ZERO, AND END 
SUBROUTINE. */ | 

ON ENOFILECINFILE) 


BEGINS 
BODY_SIZE,DATA_SIZE = 03 
GO TO 
END_READ_RPLS$ 


END$ 


4%* ASSOCIATE OHEAD_LARRAY AND 


IN_CHEAD_ARRAY WITH BODY_AREA. */ 
DUMMY_POINTER1,DUMMY_POINTER2 = 
ADDR( BODY_ AREA) 3; 

/* READ NEXT LOGICAL OQHEAD_RECORD 
FROM INFILE. */ | 

REAO FILECINFILE) SETCINPOINTER) 3 
/* ASSIGN IN_QHEADLARRAY WITHIN 
OHEAD_RECORD TO OHEAD_ARRAY. */ 
OHEAD_ARRAY = 

INPOINTER-> IN_OHEAD _ARRAY3 

/* READ NEXT LOGICAL BODY_RECORD 
FROM INFILE. */ 

READ FILECINFILE) SETCINPOINTER); 
/* ASSIGN IN_BODY_AREA WITHIN 
BODY_RECORD TO BODY_AREA. */ 
BOOY_AREA =. 
INPCINTER->IN_BODY_AREAS 

/* READ NEXT LOGICAL DATA_RECORC 
FROM INFILE. */ 

READ FILECINFILE) SETCINPOINTER)$ 
/* ASSIGN IN_DATA_AREA WITHIN 
DATA_RECORD TO DATA_AREA. */ 
DATA_AREA = 

INPCINTER->IN_DATA AREAS 


END_READ_RPL =: 


END — 


READ_RPL; 


Figure 2.14B. The READ_ RPL subroutine used to read relocatable pointer lists and relocatable lists of lists from a file 
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Chapter 3. Using Relocatable Lists 


Organizing a list in relocatable form permits the list to be 
stored in a file. Transmission of relocatable lists to and 
from files allows programs to be run in stages and also 
allows libraries of list organizations to be created and main- 
tained for use by other programs. 

The following discussions present two examples of list 
transmission. The first example processes relocatable data 
lists, and the second processes relocatable lists of lists. Both 
examples use the previously developed subroutines for 
converting, writing, and reading relocatable lists. 


AN EXAMPLE THAT TRANSMITS 
RELOCATABLE DATA LISTS 


_ Figures 3.1A through 3.1F present the TRANS _D pro- 
gram, which provides a simple illustration of how relocat- 
able data lists may be constructed and then transmitted to 
and from a file. The program performs little actual proc- 
essing of the lists and concentrates mainly on showing how 
relocatable data lists can be written into and read from a 
file. | 

TRANS _D begins by allocating list components in the 
storage area ABSOLUTE BODY _ AREA and linking the 
components into an absolute list of available storage com- 
ponents called FREE. Each component contains a single 
character as its data element. The program then uses the 
components in FREE to create two additional lists, LIST 1 
and LIST2, which contain ten components each. 


TRANS_O: 

PROCEDURE; 

DECLARE 
(LIST1L, LIST2» FREE, WORK_POINTER, 
OP, P) POINTER, 
ABSOLUTE_HEAD_ARRAY(2) POINTER, 
RELOCATABLE_HEAD_ARRAY(2) 
OFFSET (OUMMY_RELOCATABLE_AREA) , 
ABSOLUTE_BODY_AREA AREA(240), 
RELOCATABLE_BODY_AREA AREA (240), 
BOOY_SIZE FIXED DECIMAL(5) 
INITIAL (240), 
DUMMY_RELOCATABLE_AREA 
AREA BASED(DP), 
DFILE FILE RECORD /* RECFM = V */, 
1 LIST_COMPONENT BASED(P), 
2 DATA CHARACTER(1), 
2 LINK POINTER, 
BLANKS CHARACTER(70)35 
/7* WHEN FREE LIST HAS BEEN FORMED, 
GO TO NULL_LINK. */ 
ON AREA 

GO TO 

NULL_LINKS; 


ON ENDFILE (SYSIN) 
BEGINS 
CLOSE FILE(DFILE); 
OPEN FILE(DFILE) INPUTS 
GO TO OUTPUT; 


, END$ 

START: 
/* INITIALIZE. ¥*/ 
ABSOLUTE_HEAD_ARRAY = NULL3$ 
RELOCATABLE_HEAD_ARRAY = NULLO$ 
ABSOLUTE_BODY_AREA, 
RELOCATABLE_BODY_AREA = EMPTY3$ 
/* ASSOCIATE RELOCATABLE_HEAD_ ARRAY 
WITH RELOCATABLE_BODY_AREA. */ 
DP = ADDR(RELOCATABLE_BODY_AREA)$ 
/* FORM ABSOLUTE LIST OF FREE 
STORAGE COMPONENTS, AND SET DATA 
ELEMENT OF EACH COMPONENT TO 
BLANK. */ 
ALLOCATE LIST_COMPONENT 
IN(ABSOLUTE_BODY_AREA) SET(FREE)s$ 
WORK_POINTER = FREES 

REPEAT: 


ALLOCATE LIST_COMPCNENT 
IN(ABSOLUTE_BODY_AREA) SET(P)$ 
WORK_POINTER->LINK = P3; 
WORK_POINTER=>DATA = * °3 
WORK_POINTER = P3 | 
GO TO 
REPEAT$ 
NULL_LINK? 
/* IN LAST COMPONENT OF FREE LIST, 
SET LINK POINTER TO NULL AND DATA 
ELEMENT TO BLANK. */ 
WORK_POINTER->LINK = NULL3$ 
WORK_POINTER->DATA = * °3 
/* FORM ABSOLUTE LISTS», LIST1 AND 
LIST2, WITH TEN COMPONENTS EACH 
FROM FREE LIST. */ 
LIST1L, WORK_POINTER = FREE; 
DO 
I = 1 TO 93 
WORK_POINTER = 
. WORK_POINTER->LINK3 
END; 
LIST2 = WORK_POINTER->LINK3$ 
WORK_POINTER->LINK = NULL3 
WORK_POINTER = LIST23 
00 
I = 1 TO 93 | 
WORK_POINTER = WORK_POINTER=>LINK3$ 
END; | | 
FREE = WORK_POINTER=>LINK3 
WORK_POINTER->LINK = NULL3 
/* ASSIGN HEAD POINTERS LIST1 
AND LIST2 TO ABSOLUTE_HEAD_ARRAY */ 
ABSOLUTE_HEAD_ARRAY(1) = LIST13 
ABSOLUTE_HEAD_ARRAY(2) = LIST23 
OPEN FILE(DFILE) OUTPUT; 
INPUT: | | | 
/* READ TWO INPUT CARDS AND INSERT 
THE FIRST TEN CCLUMNS OF FIRST CARD 
INTO LIST1 AND THE FIRST TEN 
COLUMNS OF SECOND CARD INTO LIST2.*/ 
DO : 
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00 


WORK_POINTER = LIST1yLIST23 


I= 1 TO 103 


GET 


END; 


EDI T(WORK_POINTER->DATA)(A(1))5 
WORK_POINTER = WORK_POINTER=SLINKS 


GET EDIT( BLANKS) (A(70))3 


END; 


/* EMPTY RELOCATABLE_BODY_AREA. */ 
RELCCATABLE_BODY_AREA = EMPTY; 


— /* CONVERT DATA LISTS LISTL 


_ANO LIST2 FROM ABSOLUTE TO 


RELOCATABLE FORM. */ 

CALL CON_DAR(ABSOLUTE_BODY_AREA, 
ABSOLUTE_HEAD_ARRAY» 
RELOCATABLE_BODY_AREA, 
RELOCATABLE_HEAD_ARRAY)$ 

/* WRITE RELOCATABLE DATA LISTS */ 
CALL WRITE_ROL(DFILE, 
RELOCATABLE_HEAD_ARRAY, 


' RELOCATABLE_BODY_AREA, BODY_SIZE)3$ 


/* PROCESS NEXT TWO INPUT CARDS. */ 


GO TO 


OUTPUT: 


IF 


INPUTS 


/* READ HEAD ARRAY AND BODY AREA FOR 
NEXT SET OF RELOCATABLE LISTS */ 
CALL READ_ROL(OFILE, 
RELOCATABLE_HEAD_ARRAY, | 
RELOCATABLE_BODY_AREA,BODY_SIZE); 


BODY_SIZE = 0 


THEN 
GO TO 


PRINTS 
DO 


DO 
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END_TRANS_D$ 

/* EMPTY ABSOLUTE_BODY_AREA. */ 
ABSOLUTE_BODY_AREA = EMPTY; | 

/* CONVERT CATA LISTS FROM 
RELOCATABLE TO ABSOLUTE FORM. */ 
CALL CON_ORA(RELOCATABLE_BODY_AREA, 
RELOCATABLE_HEAD_ARRAY, : 
ABSCLUTE_BODY_AREA, 
ABSOLUTE_HEAD_ARRAY)$ 

/* ASSIGN POINTER VALUES OF 
ABSOLUTE_HEAD_ARRAY TO LIST1 

AND LIST2. */ , 

LIST1 = ABSOLUTE_HEAD_ARRAY(1)3 
LIST2 = ABSOLUTE_HEAD_ARRAY(2) $ 

/* PRINT DATA VALUES IN LIST1 IN 
SUCCESSIVE POSITIONS ON ONE LINE 
AND THOSE OF LIST2 ON NEXT LINE. */ 


WORK_POINTER= LIST1,LIST23 


I = 1 TO 103 


PUT 
EDIT(WORK_POINTER=>DATA)D (A(1))3$ 
WORK_POINTER = WORK_POINTER=—SLINK3 
END; : | | . 
PUT SKIP; 
END_PRINTSEND; 
PUT 
LIST( *#*eee? ) 5 
PUT 
SKIP(2) 5 
4* PROCESS NEXT SET OF 
RELOCATABLE LISTS IN OFILE< */ 
GO TO. = 2 
OUTPUT; 
END_TRANS_Ds: 
CLOSE: FILE(SYSPRINT)3 
CLOSE FILE(OFILE)$ 
END 
TRANS_D3$ 


Figure 3.1A. The TRANS_D program, which illustrates the 


~ construction of a relocatable data list and its 
transmission to and from a file 


LIST1 and LIST2 obtain their data values from the 
standard system-input file, SYSIN. LIST1 receives the 
characters in cc 1 through 10 of the first input card. 
Similarly, the second input card supplies the data values for 
LIST2. Sample input cards appear in Figure 3.1B,and 
Figure 3.1C shows how the characters from the first two 
input cards are arranged in LIST1 and LIST2. 


CARD10 ——-—-— 





Figure 3.1B. Sample input from SYSIN file 






ABSOLUTE_BODY_AREA 






















st eLHELHEL-EL- EL 
LETHELHELHELFEN 

usta eCHELHELHEL-EL 
Eee i mln Us Se Kel 

ree CORO 





ia ee ee 





Figure 3.1C. Examples of absolute data lists 


Next, the program assigns the head pointers of LIST] 
and LIST2 to the pointer array ABSOLUTE HEAD _ 
ARRAY and invokes the subroutine CON_ DAR, which 
was discussed in Chapter 2. This subroutine converts the 
absolute lists LIST1 and LIST2 in ABSOLUTE _BODY _ 
AREA to relocatable data lists in RELOCATABLE_BODY 
_AREA, as illustrated by Figure 3.1D. The array | 
RELOCATABLE HEAD _ ARRAY contains the offset 
heads of the relocatable lists. At this point, subroutine 
WRITE _RDL writes the relocatable lists into the file, 
DFILE, as shown in Figure 3.1E. 


RELOCATABLE BODY_AREA 


-} DDE 2 L-60 3 
J 
| 






RELOCATABLE _ 


HEAD_ARRAY: ae 
---- T+ +FDI-P OED 
‘3 


RELOCATABLE _ RELOCATABLE _ 


HEAD_ARRAY BODY_AREA 





Figure 3.1E. Sample content of DFILE (unblocked) 
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TRANS_D continues processing pairs of input cards and 
generating relocatable output for DFILE. When the end 
of the SYSIN file is reached, DFILE is closed and reopened 
as an input file. The previous processing steps are now 
_reversed. Subroutine READ _RDL retrieves each relocat- 
able head array and body area from DFILE, and subroutine 
~CON_DRA converts the retrieved lists from-relocatable to 
absolute form. The data values of absolute LIST 1 are then 
printed in successive positions on a line in the standard 
system-output file, SYSPRINT. Similarly, the data values of 
LIST2 appear on the next line, as shown in Figure 3.1F. 
- Each pair of output lines is followed by a line of five 


asterisks and a blank line. The program terminates when the © 


end of DFILE is reached. 


CARDIO ———-— 


HH HE 





Figure 3.1F. Sample output to SYSPRINT file 


AN EXAMPLE THAT TRANSMITS poor 
LISTS OF LISTS 


Figures 3.2A through 3.2F present the TRANS _L program, 
which illustrates how relocatable lists of lists may be trans- 
mitted to and from a file. This program resembles the 
previous program, TRANS_D, except that it processes — 
relocatable lists of lists. 
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TRANS_L: 


PROCEDURE$ 


DECLARE 


(LISTLeLIST2,FREE»WORK_POINTER, 
SUB1l, SUB2s DBy Py 0) POINTER: 
ABSOLUTE_HEAD_ARRAY(2) POINTER, 
RELOCATABLE_HEAD_ARRAY (2) 
OFFSET(DUMMY_RELOCATABLE_BODY) , 
(ABSOLUTE_BODY_AREA, 


RELOCATABLE_BODY_AREA, 


DATA_AREA) AREA (400)> 
DATA_SIZE FIXED DECIMAL(5) 
INITIAL (400), 

BODY_SIZE FIXED DECIMAL(5) 
INITIAL (400), 
DUMMY_RELOCATABLE_BODY 


AREA BASED(0B), 


GO 


1 LIST_COMPONENT BASED(P), 

2 TYPE CHARACTER(1), 

2 VALUE POINTER, 

2 LINK POINTER, 

DATA_ITEM CHARACTER(1) BASED(D), 
LFILE FILE RECORD /* RECFM = V */, 
COUNT FIXED DECIMAL INIT(O), 

#SUBS FIXED DECIMAL INIT(2), 
BLANKS CHARACTER (80), 

/* WHEN FREE LIST HAS BEEN FORMED, 
GO TO NULL_LINK. */ 

ON AREA 

TO 

NULL_LINK$ 

/* WHEN ALL INPUT CARDS HAVE BEEN 
READ FROM SYSIN FILE, CLOSE LFILE 
AND REOPEN IT AS AN INPUT FILE. 
THEN GO TO OUTPUT. */ 


ON ENDFILE (SYSIN) 


BEGINS 

CLOSE FILE ( 
LFILE)$ 

OPEN FILE ( 
LFILE ) INPUTS 

GO TO -s 

OUTPUTS. 

END; 

STARTS 
7* INITIALIZE. ¥*/ 
ABSOLUTE_HEAD_ARRAY = NULLS — 
RELOCATABLE_HEAD_ARRAY = NULLO3$ 
ABSOLUTE_BODY_AREA = EMPTY3$ 

 RELOCATABLE_BODY_AREA = EMPTY; 

/* ASSOCIATE RELOCATABLE_HEAD_ARRAY | 
WITH RELOCATABLE_BODY_AREA. */ 
DB = ADDR(RELOCATABLE_BODY_AREA); 
/* FORM ABSOLUTE LIST OF FREE 
STORAGE COMPONENTS. IN EACH 
COMPONENT, SET TYPE CODE TO "D* AND 
VALUE POINTER TO-NULL. */ 
ALLOCATE LIST_COMPONENT 
IN(ABSOLUTE_BODY_AREA) SET(FREE)$ 
WORK_POINTER = FREE3 

REPEAT: 


ALLOCATE LIST_COMPONENT 
INCABSOLUTE_BODY_AREA) SET (P)$ 
WORK_POINTER=SLINK = P35 
WORK_POINTER->VALUE = NULLS - 
WORK_POINTER->TYPE = *D*$ 


WORK_POINTER = P3 


GO TO 


REPEATS 


NULL_LINK: 


DO 


END; 


DO 


END; 


DO 


DO 


END; 


DO 


END; 


END; 


OPEN FILE ( 


/* IN LAST COMPONENT OF FREE LIST, 
SET LINK ELEMENT TO NULL, VALUE 
ELEMENT TO NULL» AND TYPE CODE TO 
"DY .*/ 

WORK_POINTER=>LINK = NULL3$ 
WORK_POINTER->VALUE = NULL; 
WORK_POINTER=>TYPE = *D*5 

/* FORM ABSOLUTE LISTS OF LISTS, 
LIST1 AND LIST2, FROM FREE LIST BY 
ASSIGNING 12 LIST COMPONENTS AT THE 
TOP LEVEL OF EACH LIST. */ 

LIST1 = FREE; 

WORK_POINTER = LIST1$ 


I= 1 TO 1l3 
WORK_POINTER = WORK_POINTER=SLINKS 


LIST2 = WORK_POINTER=>LINK;$ 
WORK_POINTER=SLINK = NULL; 
WORK_POINTER = LIST23 


I = 1 TO 113 
WORK_POINTER = WORK_POINTER=5SL INK3 


FREE = WORK_POINTER=>LINK; 
WORK_POINTER=>SLINK = NULL3 

4* ASSIGN HEAD POINTERS LIST1 
AND LIST2 TO ABSOLUTE_HEAD_ARRAY */ 
ABSOLUTE_HEAD_ARRAY(1) = LIST1$ 
ABSOLUTE_HEAD_ARRAY(2) = LIST2$ 
/* QRGANIZE THE 12 COMPONENTS IN 
LIST1 SO THAT THE TOP LEVEL 
CONTAINS TWO SUBLISTS WITH FIVE 
COMPONENTS EACH. OO THE SAME FOR 
LIST2. */ 


I= 1 70 23 

WORK_POINTER = 
ABSOLUTE_HEAD_ARRAY(1)5 
WORK_POINTER->TYPE = °L*5 
WORK_POINTER = WORK_POINTER=SL INKS 
WORK_POINTER=>TYPE = *L°35 

SUB1 = WORK_POINTER-SLINKS 
WORK_POINTER=>LINK = NULL3$ 
WORK_POINTER = SUB15 


J = 1 T0 43 
WORK_POINTER = WORK_POINTER->LINKS 


SUB2 = WORK_POINTER=SLINKS$ 
WORK_POINTER=>LINK = NULLS 
WORK_POINTER = SUB23 


J=1 70 45 
WORK_POINTER = WORK_POINTER=>LINK3 


WORK_POINTER=>LINK = NULL3 
WORK_POINTER = : 
ABSOLUTE_HEAD_ARRAY(1I)3 
WORK_POINTER=>VALUE = SUB13$ 
WORK_POINTER = 
WORK_POINTER=>LINKS$ 
WORK_POINTER->VALUE = SUB2; 


/* CPEN LFILE AS QUTPUT FILE. */ 


LFILE ) OUTPUTS 


INPUT: 


ENO$ 


END; 


END; 


DATA_AREA = EMPTY; 
DO WORK_POINTER = LIST1l, LIST235 


~SUB1 = WORK_POINTER=>VALUE 5 


WORK_POINTER = WORK_POINTER=SLINK; 
SUB2 = WORK _POINTER->VALUE $ 

DO WHILE(SUB1 -~= NULL); 

ALLOCATE DATA_ITEM 

IN(DATA_AREA) SET(O)3 

GET EDIT(D=>DATA_ITEM)(A(1))3 
SUB1->VALUE = D3 

SUB1 = SUB1->LINK$ 

COUNT = COUNT + 13 


DO WHILE(SUB2 -~= NULL)$ 
ALLOCATE DATA_ITEM 
IN(DATA_AREA) SET(D)$ 

GET EDIT(D—>DATA_ITEM) (CAC1))3 
SUB2->VALUE = D3 

SUB2 = SUB2->LINK$ 

COUNT = COUNT + 135 


GET EDIT (BLANKS) (A(8O - COUNT))3 
COUNT = 03 


/* EMPTY RELOCATABLE_BODY_AREA. */ 
RELOCATABLE_BODY_AREA = EMPTY; 

4* CONVERT ABSOLUTE LISTS OF 

LISTS (LIST1 ANO LIST2) TO 
RELOCATABLE FORM. */ 

CALL CON_LAR(ABSOLUTE_BODY_AREA, 
ABSOLUTE_HEAD_ARRAY, 
RELOCATABLE_BODY_AREA, 
RELOCATABLE_HEAD_ARRAY, 

DATA_AREA, #SUBS); | 
/* WRITE RELOCATABLE DATA LISTS INTO 
LFILE. */ 

CALL WRITE_RPL(LFILE, 
RELOCATABLE_HEAD_ARRAY, 
RELOCATABLE_BODY_AREA,B0DY_ SIZE, 
DATA_AREA, DATA_ SIZE)$ 

/* PROCESS NEXT TWO INPUT CARDS. */ 


GO TO 


OUTPUTS 


IF 


THEN 


INPUT; 


4* READ HEAD ARRAY, BODY AREA, AND 
DATA AREA FOR NEXT SET OF 
RELOCATABLE LISTS OF LISTS IN 
LFILE. */ 

CALL READ_RPLILFILE, 
RELOCATABLE_HEAD_ARRAY, 
RELOCATABLE_BODY_AREA, BODY_SIZE, 
DATA_AREA, DATA_SIZE)3$ 

/* IF END OF LFILE IS REACHED 
TERMINATE PROGRAM. */ 


BODY_SIZE = 0 


GO TO 


ENO_TRANS_L 3 


4* EMPTY ABSOLUTE_BODY_AREA. */ 


ABSOLUTE_BODY_AREA = EMPTY; 

/* CONVERT LISTS OF LISTS FROM 
RELOCATABLE TO ABSOLUTE FORM. */ 
CALL CON_LRA(RELOCATABLE_BODY_ AREA, 
RELOCATABLE_HEAD_ARRAY, 
ABSOLUTE_BODY_AREA, 
ABSOLUTE_HEAD_ARRAY, 

DATA_AREA, #SUBS); 

/* ASSIGN POINTER VALUES OF 
ABSOLUTE_HEAD_ARRAY TO HEAD 
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POINTERS LIST1L AND LIST2 #*/ 
LIST1 = ABSOLUTE_HEAD_ARRAY(1) 3 
LIST2 = ABSOLUTE_HEAD_ARRAY(2)3_ 
/* PRINT ALL DATA VALUES OF LIST1 IN 
SUCCESSIVE POSITIONS ON ONE LINE AND 
THOSE OF LIST2 ON NEXT LINE. */ 
PRINT? | 
DO WORK_POINTER = LISTl, LIST23 
IF WORK_POINTER = NULL 
THEN GO TO ENO_PRINT; 
SUB] = WORK_POINTER->VALUE; | 
WORK_POINTER = WORK_POINTER=>LINK3 
IF WORK_POINTER = NULL 
THEN DO3SUB2=NULL$GOTO FIRSTSEND; 
SUB2 = WORK_POINTER->VALUE; 
FIRST: | 
WORK_POINTER = SUB13 
IF WORK_POINTER = NULL 
THEN GO TO SECOND; 
DO WHILE(WORK_POINTER -= NULL); 
P = WORK_POINTER->VALUE$ 
PUT EDIT(P->DATA_ITEM)(A)3 
— WORK_POINTER = WORK_POINTER->LINK3 
END; 
SECCND: 
WORK_POINTER = SUB23 
IF WORK_POINTER = NULL 
THEN GO TO END_PRINT; 7 
DO WHILE(WORK_POINTER -~= NULL) 3 
—P = WORK_POINTER=>VALUE; 
PUT EDIT(P—>DATA_ITEM)(AD3 
WORK_POINTER = WORK_POINTER->L INK3 
ENDS | | 
PUT 
SKIP; 
END_PRINT: 
END; 
PUT 
LIST(*###84*) 5 
PuT 
SKIP(2)3 
/* PROCESS NEXT SET OF RELOCATABLE 
LISTS IN LFILE . */ 
GO TO 
| OUTPUT; 
END_TRANS_L? 
CLOSE FILE(SYSPRINT)3 
CLOSE FILE(LFILE); 
END 
TRANS_L3 


Figure 3.2A. The TRANS _L program, which illustrates the 
construction of relocatable lists of lists and 
transmission to and from a file 
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TRANS _L begins by allocating list components in the 
storage area ABSOLUTE_BODY_ AREA and linking the 
components into an absolute list of available storage com- 
ponents called FREE. The program then uses the compo- 
nents in FREE to create two absolute lists of lists, LIST 1 
and LIST2, which contain two sublists each at the top level. 
Each sublist contains five data (D) components, as shown in 
Figure 3.2C. 


CARD10 





Figure 3.2B. Sample input from SYSIN file 


ABSOLUTE_BODY_AREA 















LisTt: 
ee 
Ble Je 
oJ- IN 
Lista: Cae eee mS 
ote} Feplal | cae ose 
ojo] BRE .wem 
ol IN 
FREE: INIA 12 INNIS 





DATA_AREA 








D > DATA_ITEM 


CUR (OEE Sei e ARP l ele 





Figure 3.2C. Examples of absolute lists of lists 


DATA_AREA serves as the storage area for the data 
values associated with LIST1 and LIST2. The based variable 
DATA _ITEM is allocated in DATA _AREA. DATA_ITEM 
specifies single characters whose addresses are assigned to 
the 20 value pointers in the data components of LIST1 and 
LIST2. Input is obtained from the standard system-input 
file, SYSIN, samples for which appear in Figure 3.2B. The 
characters in cc 1 through 10 of each two input cards are 
assigned to allocations of DATA_ ITEM. Figure 3.2C illus- 
trates the association between the data content of DATA _ 
AREA and the lists of lists in ABSOLUTE. BODY AREA. 
The diagram uses compact representation for LIST1 and 
LIST2 to avoid excessive usage of arrows. 

TRANS _L now invokes the subroutine CON_ LAR, 
which converts the absolute lists of lists in ABSOLUTE _ 
BODY _AREA to relocatable lists in RELOCATABLE _ 
BODY _ AREA, as illustrated by Figure 3.2D. The array 
RELOCATABLE HEAD ARRAY contains the offset 
heads of the relocatable lists. At this point, subroutine 
WRITE_RPL writes RELOCATABLE HEAD ARRAY, 
RELOCATABLE BODY _AREA, and DATA AREA as 
separate logical records into the file LFILE (see Figure 
3.2E). | 
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RELOCATABLE_BODY_AREA 


= cs eee 
ZoCE DRea SED ED: 


EL -pPl]-. -PET]-PEL- = 


_ RELOCATABLE_ | ceo Gears aaa 


| | : 
HEAD_ARRAY: : og NS 


foe] +l] } ~ ee 


oe —— am ase eet joc cc ccc ccc cece 


-aGD-AET, BSE ona g 
{ 


foT2X 





DATA_AREA 


D~>DATA_ITEM 


cfatr|o}s |-|-[-|-]-fe jajaj] 2]—[-]-j- | 





Figure 3.2D. Examples of relocatable lists of lists 


RELOCATABLE _ RELOCATABLE _. | DATA_AREA 


HEAD_ARRAY -BODY_AREA 





Figure 3.2E. Sample content of LFILE (unblocked) 


TRANS _L contrinues processing pairs of input cards 
and generating relocatable output for LFILE. When the end 
of the SYSIN file is reached, LFILE is closed and reopened 
as an input file. The previous processing steps are now 
reversed. Subroutine READ RPTL retrieves each head array, 
body area, and data area from LFILE, and subroutine CON 
_LRA converts the retrieved lists from relocatable to 
absolute form. The data values of absolute list LIST1 are 
then printed in successive positions on a line in the standard 

- system-output file, SYSPRINT. Similarly, the data values of 
LIST2 appear on the next line, as shown in Figure 3.2F. 
Each pair of output lines is followed by a line of five | 
asterisks and a blank line. The program terminates when. the 
end of LFILE is reached. 


CARD10 


ee eH 





Figure 3.2F. Sample output to SYSPRINT file 
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SUMMARY 


This manual shows how to form a relocatable list by using 
offset variables rather than pointer variables as component 
links in the list. The values of the offset variables remain 
valid when the list is moved to a new location within inter- 
nal storage or transmitted to and from a file. 
A relocatable list can be treated as a collective unit by 

- referring to the area in which the components of the list 
have been allocated and linked. Internal and external move- 


ment of the relocatable list is then achieved by transmitting 


the containing area. 
The techniques are summarized below: 


1. A list can be treated as a collective unit by referring 
to the area in which the list components have been allo- 
cated. Internal and external movement of a list then be- 
comes possible by transmitting the containing area. 

2. The assignment statement permits the contents of 
one area to be assigned to another area. However, pointer 
values in the assigned area become invalid in the receiving 
area. | 

3. No operators can be applied to area variables. 

4. An area is made empty by assigning it the value of 
the builit-in function EMPTY or the value of another 
empty area. 

5. Assignment of an area effectively frees all alloca- 
tions in the receiving area and then assigns the content of 

the area to the receiving area. 

6. All free-storage gaps are retained within an assigned 
area, so that allocations within the assigned area maintain 
their locations relative to each other. 

7. When the source area is smaller than the receiving 
area, the assigned area is effectively extended with free 
storage. Similarly, when the source area is larger than the 
receiving area, truncation of free storage occurs at the end 
of the assigned area. However, if the truncation involves — 
allocated storage and not just free storage, the AREA ON- 
condition occurs, and the contents of the receiving area 
become undefined. 

8. A relocatable list is formed by using offset variables 
rather than pointer variables as component links in the list. 

9. An offset variable has a relative address as its value 
and is declared with the OFFSET attribute, which has the 
following form: 


OFFSET(area-variable) 


The area variable in parentheses must be based and unsub- 
scripted and must have an implied or explicit ve number 
of one. 


| es 


10. When the value of a pointer variable is assigned to 
an offset variable, the assigned pointer value is auto- 
matically adjusted so that it becomes relative to the begin- 
ning of the area associated with the receiving offset. 
variable. The address computation is equivalent in effect to 
the following calculation: 


Offset value = (Pointer value) — (Absolute address 
of area) 


11. When an offset value is assigned to a pointer vari- 
able, the offset value is automatically added to the absolute 
address of the area specified in the associated OFFSET 
attribute; the result becomes the value of the receiving 
pointer: 

Pointer value = (Offset value) + (Absolute 
address of area) | 


12. Assignment of an offset value to an offset variable is 


_ performed without address modification. 


13. The programmer cannot apply explicit arithmetic 
operations to offset variables in the source program; how- 
ever, comparisons of offset variables can be made with the 
operators equal (=) and not equal (1=). | 

14. A null offset value is assigned to an offset variable 
through the built-in function NULLO. 

15. A null offset value cannot be assigned to a pointer 
variable. Similarly, a null pointer value cannot be assigned 
to an offset variable. 

16. An offset variable cannot qualify a based variable. 
The offset value must first be assigned to a pointer variable, 
which is then used to qualify the based variable. 

17. The values of locator variables (offsets and pointers) 
cannot be converted to any other type of data, nor can any 
other type of data be converted to locator type. 

18. Locator variables may be used as arguments and 
parameters. When an offset argument is associated with an 
offset parameter, both must be offset with respect to the 
Same area. : 

19. Only record-oriented input and output statements 
can be used to transmit relocatable lists. The LOCATE 


_ Statement is used to transmit lists to a file, and the READ 


statement is used to retrieve lists from a file. 
20. The subroutines developed in this manual for proc- 
essing relocatable lists fall into five categories: 


a. Converting absolute lists to relocatable form 
b. Converting relocatable lists to absolute form 
c. Moving relocatable lists — 

d. Writing relocatable lists 
‘e. Reading relocatable lists 
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The Recursive Function Procedure CONV 


/* FUNCTION PROCEDURE CONV 
CAN BE USED WITH CON_LAR */ 

/* DECLARE CONV ENTRY | 
(POINTER, AREA(*), AREA(*), AREA(*) ) 
RETURNS (OFFSET (DUMMY_BODY_AREA)), 
DUMMY_BODY_AREA AREA BASED 
(OUMMY_POINTER), 

DUMMY_POINTER POINTERS */ 
CONV: 
PROCEDURE(LIST, 
BODY_AREA1, BODY_AREA2,DATA_AREA) 
RETURNS (OFFSET (OUMMY_ BODY_ AREA) ) 
RECURSIVES$ 
/* CONV IS A RECURSIVE FUNCTION 
PROCEOURE THAT CONVERTS A LIST OF 
LISTS IN BODY_AREA1] TO A 
RELOCATABLE LISTS OF LISTS IN 
BODY_AREA2. THE HEAD POINTER OF THE 
LIST TO BE CONVERTED IS PASSED TO 
CONV AS AN ARGUMENT. THE FUNCTION 
RETURNS THE OFFSET ADORESS OF THE 
NEW LIST IN BODY_AREA2. */ 
DECLARE 
LIST POINTER, 
O OFFSET(OUMMY_BODY_AREA), 
(DUMMY_BODY_POINTER, 
DUMMY_DATA_POINTER,»C1,C2) POINTER, 
(BODY_AREA1,BODY_AREA2 »DATA_AREA) 
AREAU*), 
DUMMY_BOOY_ AREA 
BASED(DUMMY_BODY_POINTER) AREA, 
DUMMY_DATA_AREA 
BASED(DUMMY_DATA_POINTER) AREA, 
1 COMPONENTI BASED(C1), 

TYPE CHARACTER(1), 

VALUE POINTER, 

LINK POINTER, 

D_COMPONENT2 BASED(C2), 

D_OTYPE CHARACTER(1), 


NM NM — — PM A A) 


O_OLINK OFFSET(OUMMY_BODY_AREA), 


D_OVALUE OFFSET(DUMMY_DATA_AREA), | 


1 L_COMPONENT2 BASED(C2), 
2 L_LOTYPE CHARACTER(1), 
2 L_OVALUE OFFSET(DUMMY_BODY_AREA), 
2 L_LOLINK OFFSET(DUMMY_BODY_AREA); 
IF | | 
LIST = NULL 
THEN 
RETURN(NULLO) 5 
DUMMY_BODY_POINTER=ADDR(BODY_AREA2) 3 
DUMMY_DATA_POINTER=ADOR(DATA_AREA) 3 
Cl = LIST3 
IF 
C1->TYPE = *D? 
THEN 
003 
ALLOCATE D_COMPONENT2 IN(BODY_AREA2) 
SET(C2)3 
C2->D_OTYPE = "D*; 
IF 
C1->VALUE = NULL 
THEN 
C2->D_OVALUE = NULLO3 
ELSE 
C2->D_OVALUE = C1->VALUE3 
C2->D_OLINK=CONV(C1->LINKs 
BODY_AREA1,BODY_AREA2 »CATA_AREA); 
END; 
ELSE 
DO; 
ALLOCATE L_COMPCNENT2 IN(BODY_AREAZ2) 
SET(C2)5 : 
C2->L_OTYPE = 'L*3 
C2->L_OVALUE=CONV(C1->VALUE» 
BODY_AREA1, BODY_AREA2, DATA_AREA); 
C2->L_OLINK=CONV(C1->LINK; 
BODY_AREAly BODY_AREA2y DATA_AREA)3 
END3 7 | 
O = C23 
RETURN(O)$ 
END 
CONV: 


57 


The Recursive Function Procedure CON 


/* FUNCTION PROCEDURE CON 
CAN BE USED WITH CON_LRA */ 

/* DECLARE CON ENTRY 
(OFFSET(DUMMY_BODY_AREA), AREA(*), 
AREA(*), AREA(*) DRETURNS( POINTER) » 
DUMMY_BOOY_AREA AREA BASED 
(DUMMY_PCINTER) » 

DUMMY_POINTER POINTER$ */ 

CON: 

PROCEOURE(RLIST, 
BODY_AREA1»BODY_AREA2eDATA_AREA) 
RETURNS (POINTER )RECURSIVES 
/* CON IS A RECURSIVE FUNCTION 
PROCEOURE THAT CONVERTS A 
RELOCATABLE LIST OF LISTS IN 
BOOY_AREAlL TO AN ABSOLUTE LIST OF 
LISTS IN BODY_AREA2. THE OFFSET HEAD 
OF THE LIST TO BE CONVERTED IS 
PASSED TO CON AS AN ARGUMENT. THE 
FUNCTION RETURNS THE ABSOLUTE ADDRESS 
OF THE NEW LIST IN BODY_AREA2. */ 

DECLARE 
RLIST OFFSET(DUMMY_BODY_AREA), 
(BODY_AREA1 » BODY_AREA2 sDATA_AREA) 
AREA(*), | | 
DUMMY_BODY_AREA 
BASED(DUMMY_BODY_POINTER) AREA, 
DUMMY_DATA_AREA 
BASED(DUMMY_DATA_POINTER) AREA, 
(DUMMY_BODY_POINTER, 
DUMMY_DATA_POINTER»C1,C2)POINTER, 

D_COMPONENT1 BASED(C1), 

D_OTYPE CHARACTER(1), 

DLOVALUE OFFSET (OUMMY_DATA_AREA), 

D_OLINK OFFSET(DUMMY_BODY_AREA), 

L_COMPONENT1 BASED(C1), 

L_OTYPE CHARACTER(1), 

L_OVALUE OFFSET (DUMMY_BODY_AREA), 

L_OLINK OFFSET(DUMMY_BODY_AREA), 

COMPONENT2 BASED(C2), 


= NNN NNAD = 
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2 TYPE CHARACTER(1), 
2 VALUE POINTER, 
2 LINK POINTERS 


IF 
RLIST = NULLO 
THEN | 
RETURN(NULL) 3 
DUMMY_BODY_POINTER = ADOR(BODY_AREA1)3 
DUMMY_DATA_POINTER=ADDR(DATA_AREA)$ 
Cl = RLIST3 
IF | 
C1->D_OTYPE = "D* 
THEN 
DO; | 
ALLOCATE COMPONENT2 
IN (BODY_AREA2) SET(C2)3 
C2->TYPE =. "Dt; 
IF | 
C1->O_OVALUE = NULLO 
THEN , 
— C2->VALUE = NULL3 
ELSE | 
~C2->VALUE = C1->D_OVALUE; 
C2—->LINK=CON(C1->D_OLINK, 
: BODY_AREA1,BODY_AREA2~eDATA_AREA)3 
END; | 
ELSE 
00; | 
ALLOCATE COMPONENT2 | 
IN (BODY_AREA2) SET (C2)3 
C2->TYPE = "L*; 
C2—->VALUE=CON(C1->L_OVALUE, 
BODY_AREA1»BODY_AREA2,DATA_ AREA)$ 
C2->LINK=CON(C1->L_CLINK; 
— BOOY_AREA1,BODY_AREA2,DATA_AREA); 
END; | 
RETURN (C2)3 
END | 


CON $ 


index 


AREA assignment 
Area control bytes 
AREA On-condition 
CON function 
CON_DAR subroutine 
CON_DRA subroutine 
CON_LAR subroutine 
‘CON_LRA subroutine 
CON_PAR subroutine 
CON_PRA subroutine 
CONV function 
EMPTY function 
External blocks 
External relocation 
FILE attribute 
Input/output statements 
Internal relocation | 
LOCATE statement 
Logical records 


Page 
Numbers 


3,4, 35, 37 
12 

3 

33, 58 
23, 24 
29, 30 
27, 28 
33, 34 
22520 
31532 
21,31 
3 

12 
39, 41 
11 

11 
35,37 
11 

12 


MOVE_RDL subroutine 
MOVE_RPL subroutine 
NULLO function 

Offset variables 

Output buffer 

Padding elements in structures 
Reading relocatable lists 
READ_RDL subroutine 
READ_ RPL subroutine 
READ statement 
REFER option 
Self-defining records 
SET option 

TRANS_D procedure 
TRANS _L procedure 
Type codes 

Writing relocatable lists 
WRITE_RDL subroutine 
WRITE_RPL subroutine 


Page 
Numbers 


35, 36 
37, 38 

6 

3 

11 

9,11 

43 

43, 44 
44,45, 46 
13 

17 

16 

11 

47, 48 
50, 51, 52 
9 

39 

39, 40 
40, 41, 42 - 


59 


GF20-0020-0 


BIN 


International Business Machines Corporation 

Data Processing Division 

1133 Westchester Avenue, White Plains, New York 10604 
(U.S.A. only) | 


IBM World Trade Corporation 
821 United Nations Plaza, New York, New York 10017 
(international) 


1/1id Ul s3si7] ajqezyeoojay Bursseo0sg 10} sanbiuyoa | 


0-0Z00-0249 “V'S'N U! petulid 


_ READER’S COMMENT FORM 
Techniques for Processing Relocatable | GF20-0020-0 
Lists in PL/I 


Please comment on the usefulness and readability of this publication, suggest additions and 
deletions, and list specific errors and omissions (give page numbers ). All comments and sugges- 
tions become the property of 18M. If you wish a reply, be sure to include your name and address. 


COMMENTS 











fold fold 


fold | fold 








e Thank you for your cooperation. No postage necessary if mailed in the U.S.A. 
FOLD ON TWO LINES, STAPLE AND MAIL. 


GF20-0020-0 — 


YOUR COMMENTS PLEASE... 


Your comments on the other side of this form will help us improve future editions of this pub- 
lication. Each reply will be carefully reviewed Ry the persons responsible for mene and pub- 
lishing this material. 


Please note that nequieate for copies of publications and for assistance in utilizing your IBM 
_ system should be directed to your 15M representative or the 18M branch office serving your | 
locality. — | 


FIRST CLASS 
PERMIT NO. 1359 
WHITE PLAINS, N. Y. 


BUSINESS REPLY MAIL 


NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES: 





POSTAGE WILL BE PAID BY... 


IBM Corporation 
1133 Westchester Avenue | 
White Plains, N.Y. 10604 


Attention: Technical Publications 


eoeevsesese#eeeeenwneeeeseweetrteeeeeeeeeeeeteeesee ete eeeeereeeeeee eee @ eoeoeet@eeweeeweereeeeweeeeeereeereeeteeteeeteetrteeeeeeeeeeeeee ee @ @, & 


SM 


International Business Machines Corporation 
_ Data Processing Division | 
1133 Westchester Avenue, White Plains, New York 10604 
(U.S.A. only] 


IBM. World Trade Comaration 
821 United Nations Plaza, New York, New York < 10017 
_ [International] 


MN7ZNN-N749 “WSN Ul PAI 1/7 Ul SIS! Bjqeyed0jay Buissed0ig JO} Sanbiuyoe | 


